claude-code - 💡(How to fix) Fix Voice dictation: user-configurable vocabulary hints for custom terms

Summary

Claude Code's /voice dictation auto-hints the STT engine with the project name and current git branch — useful, but limited. There is no way to supply additional project-specific vocabulary (tool names, internal terminology, technical jargon), so words like ac-django, claim-next, or domain-specific identifiers get mis-transcribed every time.

Use case

When dictating chat messages and Slack DMs into Claude Code while driving an autonomous agent workflow, project vocabulary appears constantly. Examples of recurring mis-transcriptions:

• teatree → "t three", "tea tree"
• ac-django → "AC Django", "ac jungle"
• ac-python → "AC Python"
• companion skills → "companion's skills"
• claim-next → "claim next"

Every mis-transcription either silently corrupts the message or forces the user to re-dictate. The auto-hint (project name + branch) helps for the project's own identifiers, but doesn't cover skills, tool names, custom CLI subcommands, or internal vocabulary.

Proposed feature

A voice.vocabulary array in ~/.claude/settings.json:

{
  "voice": {
    "language": "en",
    "vocabulary": ["teatree", "ac-django", "ac-python", "claim-next", "companion-skills"]
  }
}

The harness forwards this list to the STT service as additional hint terms, alongside the existing automatic project/branch hints.

Optional refinements:

• Per-project vocabulary file (e.g. .claude/voice-vocabulary.txt, one term per line) so vocab lists can live with the project they belong to.
• Phrase support (multi-word terms), not just single words.

Why a user-supplied list is the right shape

The existing automatic hint (project name + branch) is one specific case of a more general pattern: "here are the project's own identifiers, prefer them over phonetic alternatives." Extending this to a user-supplied list lets each project carry its own jargon without each user re-discovering the same mis-transcriptions.

Alternatives considered

• macOS system-level dictation custom words — does not help because Claude Code streams audio directly to Anthropic's STT, bypassing the OS dictation pipeline.
• Manual post-edit — the friction defeats the purpose of voice input.
• A hook that runs a substitution pass on transcribed text — possible workaround, but lossy (only catches exact mis-transcriptions you've seen before) and not currently wired (no post-voice hook event exists).

Acceptance

• A voice.vocabulary array in ~/.claude/settings.json whose contents are forwarded as hints to the STT engine on every /voice invocation, alongside the existing automatic project/branch hints.
• Documented in the Claude Code docs section that currently mentions the automatic hint behaviour.