Quick checklist: why /voice is not working
- Unknown command: /voice, or /voice is missing: Claude Code is not using a Claude.ai sign-in. Run /login, or remove ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper setting or a third-party provider, then restart Claude Code.
- Voice mode requires a Claude.ai account: run /login to sign in again.
- You are in an SSH session or a cloud session: /voice needs a local microphone, so it does not work there. Use the copy and paste workflow below.
- You run Claude Code in WSL: you need WSLg (WSL2) and the SoX PulseAudio backend. On WSL1, run Claude Code in native Windows.
- Linux asks for SoX or cannot open an audio capture device: install SoX, or run Claude Code on a machine that has a microphone.
- Microphone access is denied: allow microphone access for your terminal app in system settings, then run /voice again.
- Voice mode is disabled by your organization's policy: ask your organization administrator.
- Holding Space only types spaces: turn dictation on with /voice hold, or switch to /voice tap.
What /voice requires, per Anthropic's docs
Anthropic's voice dictation page lists three requirements. Claude Code streams your recorded audio to Anthropic's servers for transcription, so it also needs a working connection.
- A Claude.ai account. The speech-to-text service is not available when Claude Code is configured to use an Anthropic API key directly, Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.
- A local microphone. Voice dictation does not work in cloud sessions or SSH sessions.
- WSLg, if you run Claude Code in WSL. WSLg is included with WSL2 when installed from the Microsoft Store on Windows 10 or 11.
Transcription does not use Claude messages or tokens and does not count toward the limits shown in /usage. In tap mode, the docs say a recording stops after 15 seconds of silence or two minutes in total.
Signed in with an API key, Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry
/voice is available only while a Claude.ai account is your active sign-in. Since version 2.1.84 (March 26, 2026), Claude Code hides slash commands that are unavailable for the current auth setup, so /voice can look like it is missing rather than broken.
- If you have a Claude.ai account, run /login.
- If ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or an apiKeyHelper setting is set, or a third-party provider is configured, it takes precedence over a Claude.ai sign-in. Remove it and restart Claude Code.
- The VS Code extension follows the same rule: on a third-party provider it does not offer voice dictation.
- If your team has to use an API key or a cloud provider, /voice is not available in that setup. Dictate somewhere else and copy and paste the prompt (see the workaround below).
Over SSH, in a cloud session or in VS Code Remote
Voice dictation needs a local microphone, so it does not work in SSH sessions or cloud sessions. In the VS Code extension it is not available in VS Code Remote sessions, including SSH, Dev Containers and Codespaces, because the microphone is on your local machine and the extension runs on the remote host.
If you see Voice input is failing repeatedly and has been paused, the docs name a headless server or a remote shell with no audio passthrough as typical causes.
Workaround: speak on the computer in front of you, then copy and paste the text into the remote terminal.
In WSL on Windows
- Use WSL2 with WSLg. WSLg is included with WSL2 when installed from the Microsoft Store on Windows 10 or 11.
- If you see Voice mode could not find a working audio recorder in WSL, run sudo apt install sox libsox-fmt-pulse. Installing sox alone is not enough: WSLg routes audio through PulseAudio, and there is no /dev/snd device for the ALSA backend.
- On WSL1, or anywhere WSLg is not available, run Claude Code in native Windows instead.
- Also check Windows microphone access: Settings → Privacy & security → Microphone, with microphone access for desktop apps turned on.
On Linux: SoX and audio devices
- Claude Code records with a built-in native module. If it cannot load, Claude Code falls back to arecord from ALSA utils or rec from SoX, and /voice prints an install command if neither is available.
- Voice mode requires SoX for audio recording: install SoX with the command shown in the message, for example sudo apt-get install sox.
- Voice mode requires a microphone, but SoX could not open an audio capture device: the host has no capture device, as on a headless server or in a container. Run Claude Code on a machine with a microphone.
Microphone permission on macOS and Windows
- macOS: open System Settings → Privacy & Security → Microphone, turn on your terminal app, then run /voice again.
- macOS, terminal not listed: run tccutil reset Microphone with your terminal's identifier (com.apple.Terminal for Terminal, com.googlecode.iterm2 for iTerm2). Quit the terminal with Cmd+Q, open it again and run /voice to get a fresh prompt.
- Windows: open Settings → Privacy & security → Microphone and turn on microphone access for desktop apps, then run /voice again.
- No audio detected from microphone: make sure the right input device is the system default and is not muted. On Windows, check Settings → System → Sound → Input. On macOS, check System Settings → Sound → Input.
Holding Space does nothing
- If spaces keep piling up while you hold Space, dictation is probably off. Run /voice hold.
- If one or two spaces appear and then nothing happens, hold detection is not triggering. It relies on key-repeat events from your terminal, so switch to /voice tap if key-repeat is turned off.
- In tap mode, the first tap only starts recording when the prompt input is empty.
Connection, sign-in and policy errors
- Voice connection failed: the recording never reached the transcription service. Check your network and try again.
- Voice stream error: WebSocket upgrade rejected with HTTP and a 400-range status: usually a stale sign-in, or a proxy or bot-protection service on your network. Run /login and check for a VPN or proxy.
- Voice mode is disabled by your organization's policy: an administrator has turned voice dictation off. Contact your organization administrator.
Workaround: dictate in Whispek, review, then copy and paste
When /voice isn't available, dictate the prompt in Whispek instead. It works on Windows, Mac and Linux, whatever account or machine Claude Code runs on, and "um"s and restarts are cleaned up before you paste.
- Open a notes window, a chat box or an editor scratch file next to your terminal.
- Press your Voice input shortcut and describe the task: Right Alt on Windows, Right Option on macOS, Left Ctrl + Left Alt + Space on Linux. You can change the Voice input shortcut on the Home screen.
- Review the text. Check file names, numbers and negations. To tidy it, select the text and run Create an AI prompt in Transforms.
- Copy and paste it into the Claude Code terminal, add exact paths and errors yourself, read it once and press Enter. If the text did not appear where you expected, copy it from History.
The same steps work over SSH, in WSL and with an API key or cloud provider, because the text is written on your computer and pasted into the session. Whispek does not connect to your Claude account, read your repository, send prompts or run commands. Recognition and AI features run in the cloud, so only dictate project details you may process that way.
If you sign in with a Claude.ai account and work on a local machine, try /voice first. For the full Claude Code workflow, see voice dictation for Claude Code.
Official sources
Verified against Anthropic docs on October 18, 2026. Claude Code changes often, so check the docs if a message differs from what you see.