Dictionary

The Dictionary is a list of exact, deterministic substitutions applied to the transcript. If the speech-to-text produces X, Voice Mode writes Y instead. Use it when a specific word or phrase is consistently misheard, or for names and jargon the STT doesn’t know.

The Dictionary is free and changes take effect on the next transcription after the user saves — no restart.

(In earlier releases this feature was called “Replacements.” The on-disk file is still ~/.config/voicemode/replacements.txt, but the user-facing concept is now the Dictionary, reachable from the Dashboard sidebar.)

Examples

• “mike 80” → “mhkey”
• “coup date” → “kubectl”
• “get hub” → “GitHub”

Where it fits in the pipeline

Dictionary substitutions run before the LLM correction pass, so they’re predictable — the corrector sees the already-replaced text. If the user has correction turned off, the Dictionary is still the way to fix specific words.

Built-ins vs. user entries

Voice Mode ships with a built-in dictionary of common substitutions (brand names, tech jargon, common STT misreads). The user’s entries layer on top:

• User entries are added to the built-ins.
• If a user entry has the same spoken form as a built-in, the user’s wins.
• Users can disable specific built-ins they don’t want.

When to reach for the Dictionary

• A specific phrase is always misheard the same way → add an entry.
• A name, brand, or piece of jargon never gets transcribed correctly → add an entry.
• The user wants their overall writing style tweaked (tone, formatting, punctuation conventions) → that’s not a Dictionary job; it’s a job for AI Correction, which the user can enable from the Dashboard’s AI Writing pane.

Pro tips

• Dictionary entries aren’t just for fixes — they’re shortcuts. Map a phrase to a long string the user types often. For example: “my LinkedIn profile” → the actual URL. “my email signature” → the full multi-line block. “my address” → the full address. The user can dictate the shorthand and Voice Mode pastes the real thing.
• Use phrases that aren’t normal speech. “My LinkedIn profile” is fine because it’s a phrase, not a single word the user might say in conversation. Replacing “address” alone would fire every time the user says the word “address” in any context.
• Chain the Dictionary with AI Correction. Dictionary entries run first, so a shorthand like “boilerplate intro” can expand to a full paragraph and then AI Correction can polish punctuation around it.
• Replace common typos of names. If the user’s name is “Mhkey” but STT keeps writing “Mike”, a Dictionary entry fixes it everywhere without retraining the model.

Inspecting the user’s Dictionary

If the user asks “what’s in my dictionary?” or wants to know whether a specific entry exists, call the list_dictionary MCP tool rather than reading replacements.txt directly. The tool returns the user’s overlay only (built-ins are excluded as noise) and respects the running app’s view of state. See tools.md.

There is no add_replacement / remove_replacement MCP tool, and there will not be one. Dictionary output feeds the auto-paste path that Voice Mode uses to type into other apps — the same channel that already holds macOS Accessibility permission. Letting an agent add or remove entries would mean an agent could inject arbitrary keystrokes (including newlines that act as Enter) into whatever app the user has focused. That’s a stronger primitive than any other Voice Mode setting, so the write surface stays in the Dictionary UI only.

If the user wants to add or change a Dictionary entry, point them at the Dashboard → Dictionary. Don’t edit replacements.txt directly — it races with the running app.