Claude Code voice dictation: hold, tap, and what stops it

Find the situation you are in

• I have never used it and I want to know what it does and what it costs.
• I want it on, in the mode that suits me.
• Hold to talk is awkward and I want the record-and-send version instead.
• It will not start at all and I want to know what it needs first.
• My language is not English, or the words come out wrong.
• Space is the wrong key for me.
• It printed a message and I want to know which one means what.

Dictation is a small, well-documented feature with a short list of requirements, so most questions about it end here. If the problem is getting text in by keyboard or clipboard rather than by voice, the copy and paste guide owns that. If you are trying to hold a conversation with Claude out loud rather than dictate a prompt, this is the wrong page: dictation writes text into the prompt box, and nothing more.

What voice dictation is

Voice dictation turns speech into text inside the prompt input, live, as you talk. You can mix voice and typing in the same message: dictate a sentence, type a file path, dictate the rest. It is not a spoken conversation with Claude and it does not read anything back; the transcript simply lands where your cursor was.

Where you can use it is narrower than the feature name suggests. Anthropic documents it for the terminal CLI, and for the VS Code extension. The desktop app is the odd one: its own page never mentions dictation, its Linux page says voice input is not available in the Linux desktop app and points you at the CLI instead, and yet users report the Code tab on macOS has dictation, which is what one of the open reports is about. Treat the CLI and the VS Code extension as the two documented surfaces, and the desktop app as the one you find out about by using it.

The audio does leave your machine. Your speech is streamed to Anthropic's servers and transcribed there, not on your computer, and the page says so in as many words. What it does not do is bill you for it: transcription does not consume Claude messages or tokens and does not count toward the limits /usage shows.

The transcription is tuned for coding vocabulary rather than dictation in general. Development words such as regex, OAuth, JSON and localhost are recognised, and Claude Code adds your current project name and git branch name as recognition hints, so those names are not left to the general vocabulary.

Turn it on

Run /voice. Claude Code runs a microphone check, and on macOS that is what triggers the system microphone permission prompt for your terminal if it has never been granted. You get one line back telling you the mode and the language:

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

The command takes a mode as an optional argument: /voice on its own toggles dictation on or off while keeping the mode you were in, /voice hold and /voice tap enable it in that mode, and /voice off disables it.

If you have an older settings file, it may carry the single key voiceEnabled instead. That key is deprecated since v2.1.92, when the voice object replaced it, and it still works: Claude Code reads it so old files keep behaving, and voice.enabled wins when a file carries both.

The setting persists. Once you have turned dictation on it survives a restart, and you can set it without the command at all by writing the options straight into your user settings file:

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

For the first three sessions with dictation on, an empty prompt box shows a hold space to speak hint in the footer. It follows whichever key you have bound, updates when you rebind it, and reads the same in both modes. It also disappears if you have a custom status line configured, which is worth knowing before you go looking for a hint that a status line is hiding.

Hold to record, the default

Hold mode is push-to-talk: recording runs while you hold the key and stops when you let go. Hold Space and the footer shows keep holding… during a short warmup, then listening… once recording is live. The cursor turns into a bar that rises and falls with your microphone level, unless you have reduced motion turned on.

The warmup exists because Claude Code cannot see a key being held; it watches for the rapid key-repeat events your terminal sends. That has two side effects worth expecting. The first couple of repeat characters type into the prompt and are removed again when recording starts, and a single tap of Space still types one ordinary space, because hold detection only fires on a rapid repeat.

Holding or tapping Space starts dictation only where that keypress would otherwise have typed into the prompt. In the transcript viewer Space pages through the conversation, and in vim mode outside INSERT it is a command, so neither starts a recording. A rebound modifier combination such as meta+k never types text, so it starts dictation from those places too.

If the warmup annoys you, either switch to tap mode or rebind to a modifier combination, because a modifier combination starts recording on the first press. Your speech appears in the prompt as you speak, dimmed until the transcript is final, and the text is inserted at the cursor with the cursor left at the end, so you can hold again to append, or move the cursor first and dictate somewhere else in the message.

Hold mode also works one step away from the prompt. While a background session's dispatch box or a peek-panel reply has focus, holding the key dictates into that session, so you can answer a running agent without bringing the main session to the front.

By default, releasing the key inserts the transcript and waits for you to press Enter. Set "autoSubmit": true in the voice settings object and the prompt is sent on release instead, as long as the transcript is at least three words long.

Tap to record and send

Tap mode trades the hold for two taps. With the prompt empty, tap Space once to start recording and the footer shows ● REC · tap to send; tap again to stop. There is no warmup, and you do not keep the key down.

That second tap is also the send. Claude Code inserts the transcript and submits the prompt automatically when it is at least three words long, and a shorter transcript is inserted without being sent, so an accidental tap does not post a stray word. That is the part worth knowing before you use it: tap mode does not wait for your review.

The three-word rule counts words rather than spaces, so Japanese, Chinese and Thai transcripts count individual words and do auto-submit, in tap mode and in hold mode with autoSubmit. The first tap only starts recording when the prompt is empty, so you can still type ordinary spaces while composing; the second tap stops recording whatever the input holds. Recording also ends on its own after 15 seconds of silence or two minutes in total.

Cancel instead of keeping it

Press Esc or Ctrl+C to throw a recording away. Claude Code stops the microphone, discards the transcript and restores the prompt to whatever it held before you started. Both keys also cancel while a finished recording is still being processed, and a prompt you edited or submitted in the meantime stays as you left it.

Neither key does its usual job during that press: Esc does not interrupt Claude's response, and Ctrl+C does not clear the prompt or count as the first of the two presses that exit Claude Code. That is deliberate, and it means a cancel is always safe to reach for.

What it needs, and where it will not work

The speech-to-text service only exists for a claude.ai account. It is not available when Claude Code is signed in with an Anthropic API key directly, or on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. If you are running Claude Code on a company provider, dictation is simply not part of the deal, and no setting changes that.

It needs a microphone on the machine running Claude Code, and the documentation says outright that it does not work in cloud sessions or SSH sessions. On Windows under WSL it needs WSLg, which ships with WSL2 when installed from the Microsoft Store on Windows 10 or 11; without it, on WSL1 for example, run Claude Code in native Windows instead.

Recording uses a built-in native audio module on macOS, Linux and Windows. On Linux, if that module cannot load, Claude Code falls back to arecord from ALSA utils or rec from SoX, and if neither is installed /voice prints the install command for your package manager.

The VS Code extension supports dictation under the same claude.ai account requirement, and it is not available in VS Code Remote sessions, which includes SSH, Dev Containers and Codespaces, because the microphone is on your local machine and the extension runs on the remote host. On the Anthropic desktop app, the Linux page still lists dictation as not available there and sends you to the CLI, while a report opened on 2026-10-26 argues that line is out of date because dictation works in the Linux desktop app now.

Change the dictation language

Dictation reads the same language setting that controls the language Claude answers in. Leave it empty and dictation assumes English. In the VS Code extension an empty language falls back to VS Code's own accessibility.voice.speechLanguage setting before it assumes English.

Twenty languages are supported: Czech, Danish, Dutch, English, French, German, Greek, Hindi, Indonesian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Russian, Spanish, Swedish, Turkish and Ukrainian. Set the language in /config or in settings, using either the BCP 47 code or the language name, for example "language": "japanese".

If your language is not on that list, /voice warns you when you enable it and falls back to English for dictation. Claude's written answers still come back in the language you asked for, because the fallback only applies to speech.

Rebind the dictation key

The dictation key is the voice:pushToTalk action in the Chat context, and it defaults to Space. One binding drives both modes. Rebind it in your keybindings file:

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

The action uses one key at a time: binding a custom key replaces the default Space rather than adding a second trigger, so the "space": null line above is there for clarity and you can leave it out. Some keys never reach a terminal application and cannot be bound at all; Caps Lock is the documented example and shows an error if you try.

In hold mode, avoid binding a bare letter such as v, because hold detection relies on key-repeat and that letter would type into the prompt during the warmup. Use Space, or a modifier combination such as meta+k that starts recording on the first press. Tap mode has no warmup, so most keys work there.

When it will not work: what each message means

Anthropic documents a message for most failures, and the message names the cause more precisely than the symptom does. Start here rather than with the setting.

Two failure messages look the same but are not. No audio detected from microphone means recording started and captured silence, so check the input device and its level. Voice connection failed means the audio never reached the transcription service, so check the network. Before v2.1.200 a silent microphone could report a connection failure instead, which suggested a network problem that was not the real one.

A Voice stream error: WebSocket upgrade rejected with HTTP <status> is not an outage: a server answered and refused the connection. A status in the 400 range usually means a stale sign-in or a proxy answering in place of the transcription service, so run /login and check for a VPN or proxy on the path. Claude Code retries once for a status outside the 400 range, and doesn't retry a 400-range one.

One more connection message hides a proxy. A Dictation error: WebSocket error: followed by a certificate error such as unable to get local issuer certificate means something on your network is inspecting TLS and Claude Code does not trust its certificate. The fix is on Anthropic's VS Code page, under the dictation and proxy section: point NODE_EXTRA_CA_CERTS at your organisation's root certificate in the env block of your settings file.

If the service heard you but recognised no words you get No speech detected: speak closer, cut the background noise, and make sure the dictation language matches what you are saying. In the VS Code extension a recording also ends after 15 seconds without recognised words or two minutes in total, keeping whatever words it already had. Garbled text or the wrong language is almost always the language setting, which defaults to English.

On macOS, if your terminal is not listed in the microphone settings at all, there is no toggle to turn on: reset that one app's permission with tccutil reset Microphone <bundle-id>, using com.apple.Terminal or com.googlecode.iterm2 for the two common terminals, then quit the terminal with Cmd+Q and reopen it. Running tccutil reset Microphone with no bundle ID revokes the microphone for every app on the machine, so do not do that one in the middle of a call.

What other people are reporting

These are open reports in Anthropic's issue tracker as we write this, not Anthropic statements, and none of them reports a fault this page can fix. They are worth reading because between them they describe the gaps this page cannot close: the desktop app's dictation, languages the service does not carry, and a documentation line one reporter says has gone stale.

• Issue 98004, open since 2026-09-28: a request for Hebrew support in voice dictation. 16 reactions, 1 comment.
• Issue 97929, open since 2026-09-28: a request for a configurable dictation shortcut in the desktop app. 11 reactions, 5 comments.
• Issue 101323, open since 2026-10-11: in the desktop Code tab on macOS, the transcript stopped appearing live while speaking and now shows only when recording stops. 5 reactions, 2 comments.
• Issue 98502, open since 2026-09-30: a request for tap mode to insert without sending, and to start recording when the prompt already holds text. 4 reactions, 2 comments.
• Issue 97939, open since 2026-09-28: a request for dictation in VS Code Remote-WSL windows, where the microphone is available through WSLg. 2 reactions, 1 comment.
• Issue 105297, opened 2026-10-26: the documentation's line that dictation is unavailable in the Linux desktop app is out of date, because dictation works there. No reactions or comments yet.

Four of those are requests rather than bugs, and reading them as a defect report will send you looking for a fault that is not there: tap mode sending on the second tap is the documented design, Hebrew is not one of the twenty supported languages, the desktop app documents no configurable dictation shortcut to change, and VS Code Remote is excluded on purpose. The other two are different: one describes a broken transcript in the desktop Code tab, and the other disputes a documentation line.

Where this page stops

This page owns speech going into the prompt box: the command, the two modes, the key, the language, the requirements and the messages. Three neighbours own the rest.

• Text you paste or type, and why a paste breaks in a particular terminal, belongs to the copy and paste guide.
• A custom status line hiding the footer hints, including the dictation hint, belongs to the status line guide.
• A blank or broken VS Code panel is the subject of the VS Code extension guide, which also covers a report that dictation software cannot paste into one particular tab.

Everything else about a session, from permissions to context, is covered by the other Claude Code guides.

Omniscio and dictation

Omniscio is the desktop app we make for running many Claude Code sessions at once. Claude Code's own dictation has nowhere to run in the Claude sessions the app starts: those run claude in print mode with stream-json input and output, so there is no interactive prompt box for /voice to write into.

The app also has a terminal: a real shell in a tab rather than a managed session, where claude runs interactively and /voice is available as it is anywhere else. It is an in-development feature: off by default, and switched on in Settings > Lab. We have not tested dictation there, and the operating system's microphone permission for the app is the first thing to check if you try it.

What the app does have is dictation of its own, and it is a different design. FlowVoice is an OS-wide hotkey: you hold it, speak, release, and the transcript is pasted at the cursor in whichever app has focus, on macOS and Windows. It is not Claude Code's /voice and it does not need a claude.ai account, because it never talks to Claude Code at all; the words arrive the same way a paste does. That makes it the way to dictate into a terminal running Claude Code on an API key, on Bedrock, or anywhere else /voice refuses to start, and inside Omniscio the same transcript lands in the session composer. It is off by default, and you turn it on in Settings > Voice Control under Dictation (FlowVoice); the detail is in the FlowVoice library page.

One piece of history matters if you have read older material about the app. Omniscio used to carry an in-app dictation that delivered a transcript into the active session's composer; that is retired, and FlowVoice is the only dictation in the app now.

If you are running several sessions at once, the features page lists what the app does and the download page has the installers.

Sources

Every Claude Code behaviour on this page rests on one of these pages, and each was read on the date beside it.

• Voice dictation, for the command, both modes, the cancel keys, the language list, the rebind, the requirements and every message quoted on this page. Read October 27, 2026.
• Settings reference, for the voice object, the deprecated voiceEnabled key and the language setting dictation borrows. Read October 27, 2026.
• Commands, for /voice and the account it requires. Read October 27, 2026.
• Keybindings, for voice:pushToTalk in the Chat context. Read October 27, 2026.
• Interactive mode, for the keyboard table and the places Space means something else. Read October 27, 2026.
• VS Code extension, for dictation there, its account requirement and the Remote-session limit. Read October 27, 2026.
• Claude Code in the desktop app, which documents the Code tab and does not mention dictation. Read October 27, 2026.
• Desktop app on Linux, for the line saying dictation is not available there. Read October 27, 2026.
• Changelog, for the version notes on the pause, the silent-microphone message and the WebSocket upgrade message. Read October 27, 2026.
• Data usage, for where the audio goes. Read October 27, 2026.
• The six issue pages linked above, each read on October 27, 2026, with its state, reaction count and comment count taken from the issue itself.
• Two capture runs on this machine on October 27, 2026: claude --version, which printed 2.1.311 (Claude Code), and a text search of that installed build for the dictation binding and the enable message.

Dictation changes with releases: the changelog carries dozens of voice entries, several of them fixes to messages quoted here. If a release note mentions voice, re-read the dictation page before trusting a copy of this one from last month.

Common questions

Does Claude Code voice dictation use tokens or messages?

No. Anthropic's page says transcription does not consume Claude messages or tokens and does not count toward the limits shown in /usage. Your audio is still sent to Anthropic's servers to be transcribed, so the trade is privacy, not spend: if you would rather nothing left the machine, type instead or use an on-device dictation tool.

Why does /voice say unknown command?

The dictation service only exists for a claude.ai account, and anything else wins over that sign-in: ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper setting, or a third-party provider such as Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. Remove that credential, run /login, and restart Claude Code.

Does voice dictation work over SSH or in Anthropic's cloud sessions?

No. Anthropic's requirements list a local microphone, and say voice dictation does not work in cloud sessions or SSH sessions. The VS Code extension has the same limit on remote work: it does not offer dictation in Remote sessions, which includes SSH, Dev Containers and Codespaces, because the microphone is on your local machine and the extension runs on the remote host.

How do I stop Claude Code sending the prompt when I release the key?

Leave autoSubmit out of the voice settings object, or set it to false. By default Claude Code inserts the transcript and waits for you to press Enter; autoSubmit, which applies in hold mode, sends the prompt on release once the transcript is at least three words long. In tap mode the second tap sends, so switch to hold mode with /voice hold if you want to review the text first.