Claude Code voice mode: how to enable /voice and fix it

Published 18 October 2026

Claude Code has a built-in dictation mode. You turn it on with /voice, hold Space and talk, and the words appear in the prompt. This guide covers how to enable dictation in Claude Code, the settings worth changing, and what to check when Claude Code dictation is not working.

What you need

Anthropic lists three requirements. You must be signed in with a Claude.ai account: dictation isn't available when Claude Code uses an Anthropic API key directly, Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. You need a local microphone, so it doesn't work in cloud or SSH sessions. And on WSL you need WSLg. The audio is streamed to Anthropic's servers for transcription and isn't processed locally, but it doesn't consume tokens or count toward /usage.

Enable dictation in Claude Code

Run /voice. Claude Code checks the microphone, and on macOS your terminal gets the system permission prompt if it never had one. The command takes a mode: /voice hold, /voice tap or /voice off. The setting persists across sessions, and you can also put it in your user settings file:

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

Transcription is tuned for coding vocabulary. Anthropic says terms like regex, OAuth, JSON and localhost come out right, and your project name and git branch are added as recognition hints.

Hold or tap

Hold is the default. Hold Space and talk. Claude Code spots a held key by watching key-repeat events from the terminal, so there's a short warmup: the footer shows "keep holding…" and then "listening…". The words appear dimmed as you speak and are inserted at the cursor when you let go. By default it then waits for Enter. Add "autoSubmit": true to the voice settings to send on release when the transcript has at least three words.

Tap has no warmup. With an empty prompt, tap Space once to start and again to stop and send. Transcripts shorter than three words are inserted but not sent, so a stray tap won't fire off a prompt. Recording stops on its own after 15 seconds of silence or two minutes in total, which is worth knowing before you describe a long bug. Press Esc or Ctrl+C in either mode to throw the recording away.

Language and key

Dictation follows Claude Code's language setting and defaults to English. Twenty languages are supported, including German, Japanese, Russian and Spanish. If your setting isn't one of them, /voice warns you and falls back to English.

The key is the voice:pushToTalk action in the Chat context. To move it off Space, edit ~/.claude/keybindings.json:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": { "meta+k": "voice:pushToTalk" }
    }
  ]
}

A modifier combination like meta+k starts recording on the first press, with no warmup. Avoid a bare letter in hold mode, because it types into the prompt during warmup. Some keys, Caps Lock among them, never reach the terminal and can't be bound.

Claude Code dictation not working: what to check

  1. "Unknown command: /voice" or "Voice mode requires a Claude.ai account": run /login, and remove ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or an apiKeyHelper, which win over a Claude.ai sign-in.
  2. "Microphone access is denied": enable your terminal in System Settings → Privacy & Security → Microphone. If it isn't listed, run tccutil reset Microphone com.apple.Terminal (or com.googlecode.iterm2 for iTerm2), quit the terminal with ⌘Q, reopen it and run /voice. Don't run the reset without a bundle ID: that revokes the microphone from every app.
  3. Holding Space only types spaces: if spaces keep piling up, dictation is off, so run /voice hold. If one or two appear and then nothing, key repeat is probably disabled in macOS. Switch to /voice tap.
  4. "No audio detected from microphone": check System Settings → Sound → Input and the input level.
  5. "Voice connection failed": the audio never reached the service. Check your network, VPN or proxy.
  6. Wrong language or garbled text: set the language in /config.

When a system-wide app fits better

/voice is the shortest path if you live in Claude Code on a Claude.ai account. It stops short when you work over SSH, use an API key, want speech kept on your machine, or want the same key in Cursor, Slack and your browser. Voice dictation in Claude Code and the terminal covers why terminals trip up some dictation tools.

FnFlow is one option. Hold fn (or right ⌘), describe the task, let go. Whisper transcribes the whole take on your Mac and the text goes into the terminal with a single ⌘V, and your clipboard comes back afterwards. Because it pastes into the terminal window, it doesn't care which account Claude Code uses or whether the shell is remote. Add project names to Settings → Vocabulary and Whisper uses them as spelling hints. It's free, with no word limit.

The limits: FnFlow knows nothing about Claude Code, so it won't add your git branch as a hint or submit the prompt for you. It needs an Apple silicon Mac with macOS 15 or later. The two coexist, since /voice uses Space and FnFlow uses fn. For more on wording, see dictating prompts for AI tools.

Dictate into Claude Code, locally, over any connection.Free · macOS 15 or later · Apple Silicon · 187 MB
Download FnFlow

Questions

Why does Claude Code say "Unknown command: /voice"?

/voice only exists while a Claude.ai account is your active sign-in. If ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper setting or a third-party provider is set, it takes precedence. Remove it, restart Claude Code and run /login.

Is Claude Code dictation processed locally?

No. Anthropic's docs say recorded audio is streamed to Anthropic's servers for transcription. It doesn't use Claude messages or tokens and doesn't count toward /usage.

Can I send the prompt automatically when I stop talking?

Yes. Tap mode sends it on the second tap if the transcript has at least three words. In hold mode, set "autoSubmit": true in the voice settings.

Does /voice work over SSH?

No. It needs a local microphone, so it doesn't work in SSH or cloud sessions. A dictation app on your own Mac pastes text into the terminal window instead, so it works with a remote shell too.

More from the blog
Local Wispr Flow alternativeFnFlow vs VoiceInkVoice input for CursorHow 7 Mac dictation apps get you to your first dictationWhisper.cpp on Apple Silicon: which large-v3-turbo quantization to shipHow I built a local dictation appVoice dictation in Claude Code and the terminalWhy holding fn doesn't work for dictation on Mac (and how to fix it)How to run Whisper locally on an Apple Silicon MacSpokenly alternative for developersFnFlow vs EnviousWisprHow to dictate a good prompt for AI coding toolsVoice dictation in VS Code on a MacTeaching Whisper your jargon: initial prompt and replacementsWhy Whisper types "Thank you" on silence, and how to filter itPrivate dictation on a Mac at work: what actually leaves your machineVoice input for Codex CLI and the ChatGPT appVoice coding on a Mac: what actually worksWriting git commit messages by voiceDictating code review comments on GitHubDictation in IntelliJ IDEA, PyCharm and WebStorm on a MacDictation in Zed on a MacDictation in Terminal, iTerm2 and WarpWhich Whisper model to use on an Apple Silicon MacPush-to-talk dictation on a Mac: hold, toggle or streamSuperwhisper alternative for developersWhisper apps: five ways to run Whisper locallyTalon voice coding vs a dictation appPush to talk on a MacDoes Claude have a voice mode?VoiceInk vs Wispr FlowVoiceInk vs SuperwhisperParakeet vs Whisper on a MacApple SpeechAnalyzer vs WhisperWhisper.cpp vs faster-whisper on a MacMlx-whisper vs whisper.cppGitHub Copilot voice inputGemini CLI voice inputVoice input in Google AntigravityVibe coding with voice input