Context Awareness
Use selected text, clipboard text, and visible screen text in AI-enhanced Modes.
What Context Awareness Does
Context Awareness lets an AI-enhanced Mode use surrounding information when shaping the final output. The Mode can include:
| Context source | How VoiceInk gets it |
|---|---|
| Selected Text | Reads the current selection through macOS Accessibility. |
| Clipboard | Reads text currently on the clipboard at recording start. |
| Screen | Captures the active window and extracts visible text with OCR. |
At live recording start, VoiceInk prepares a local, in-memory context snapshot. Clipboard and selected text can be read then, and screen text can be captured when Screen Recording permission allows. The Mode's source switches control which parts are included in the enhancement request, rather than preventing every local snapshot read.
This context is supplied to AI Enhancement. Plain Dictation Modes without enhancement do not send it to an enhancement provider. VoiceInk Refine ignores these sources and uses only the dictation text. Imported audio and video files do not capture live context.
Enable Context for a Mode
- Open Modes.
- Edit a Mode with AI Enhancement enabled.
- Expand Context Awareness.
- Turn on Selected Text, Clipboard, or Screen.
- Save the Mode.
Permissions
| Context source | Required permission |
|---|---|
| Selected Text | Accessibility |
| Clipboard | No extra permission |
| Screen | Screen Recording |
If Accessibility is missing, selected text is skipped. If Screen Recording is missing, screen context is skipped.
Screen Context
For Screen context, VoiceInk captures the active window, runs OCR locally with Apple's Vision framework, and sends extracted text to the AI provider as part of the prompt context. The screenshot image itself is not the context payload. Available AI request metadata saved in History can contain the extracted context text that was sent.
Prompt Tags
When you enable a context source for a Mode and that context is available, your custom prompts can refer to it by tag:
| Tag | Context |
|---|---|
<CURRENTLY_SELECTED_TEXT> | Selected text. |
<CLIPBOARD_CONTEXT> | Clipboard text. |
<CURRENT_WINDOW_CONTEXT> | Text extracted from the active window. |
For the full input format, see Creating a Custom Prompt.
Good Uses
- Rewrite selected text by speaking an instruction.
- Draft a reply using a selected email or message thread.
- Ask the Assistant about visible content in the active window.
- Preserve names, tasks, or dates from nearby text.
Privacy
Only enable sources useful for the task, and consider which provider will receive their text. Local transcription does not make cloud enhancement local. See Privacy and Data.