1. “Unknown command: /voice” or “Voice mode requires a Claude.ai account”
Anthropic says /voice is available only while a Claude.ai account is your active sign-in. Setting ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper, or a third-party provider takes precedence over that sign-in, so the command disappears even if you logged in through the browser earlier. The documented exclusions are an Anthropic API key used directly, Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry. The free Claude.ai plan does not include Claude Code at all.
“Voice mode requires a Claude.ai account” is the related case where Claude Code cannot find a usable Claude.ai sign-in when you enable voice or start recording; /login usually fixes it. “Voice mode is disabled by your organization's policy” is different again: an administrator has turned dictation off, and only that administrator can change it.
- Unset ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN, and remove any apiKeyHelper setting.
- Restart Claude Code and run /login with your Claude.ai account.
- Run /voice; it should answer “Voice mode enabled (hold). Hold space to record.”
- If the message names your organization’s policy, ask your admin instead of reinstalling.
2. “Microphone access is denied” or “No audio detected from microphone”
On macOS the first /voice run triggers the system microphone prompt for your terminal app, not for Claude Code itself. If you dismissed it, enable the terminal under System Settings → Privacy & Security → Microphone. If the terminal is missing from that list, Anthropic documents a reset: run tccutil reset Microphone with the terminal’s bundle ID (com.apple.Terminal for Terminal, com.googlecode.iterm2 for iTerm2, or the result of osascript -e 'id of app "AppName"'), quit the terminal with ⌘Q rather than closing its windows, reopen it, and run /voice again. Running the reset without a bundle ID revokes microphone access from every app, including Zoom and Slack.
On Windows, turn on microphone access for desktop apps under Settings → Privacy & security → Microphone. “No audio detected from microphone” is a different problem: recording started but captured silence. Select the correct default input under Settings → System → Sound → Input on Windows or System Settings → Sound → Input on a Mac, and make sure its level is not muted or near zero.
3. Linux, containers and WSL: the audio recorder messages
Claude Code records through a built-in native module. On Linux, if that module cannot load, it falls back to arecord from ALSA utils or rec from SoX. “Voice mode requires SoX for audio recording” means neither fallback is installed, and the message prints an install command for your package manager, such as sudo apt-get install sox.
“Voice mode requires a microphone, but SoX could not open an audio capture device” means SoX is present but the host has no input device, which is expected on a headless server or inside a container. Anthropic says v2.1.195 and later report this precisely; earlier versions asked for SoX even when it was installed. No package fixes it: run Claude Code on a machine that has a microphone.
WSL is its own case. WSLg routes audio through PulseAudio, and WSL has no /dev/snd device, so installing sox alone pulls in an ALSA backend that cannot record. For “Voice mode could not find a working audio recorder in WSL”, install the PulseAudio backend explicitly. WSLg comes with WSL2 installed from the Microsoft Store on Windows 10 or 11; on WSL1, Anthropic says to run Claude Code in native Windows instead.
- Desktop Linux without the native module: sudo apt-get install sox.
- WSL2 with WSLg: sudo apt install sox libsox-fmt-pulse.
- WSL1: run Claude Code natively on Windows for /voice.
- Headless server or container: there is nothing to record from.
4. SSH, cloud sessions and VS Code Remote cannot reach your microphone
A local microphone is one of Anthropic’s three requirements, and the documentation is explicit that dictation does not work in SSH sessions or in Claude Code’s cloud sessions on the web. The VS Code extension supports dictation with the same Claude.ai requirement, but not in VS Code Remote sessions, including SSH, Dev Containers and Codespaces, because the extension runs on the remote host while the microphone stays on your machine.
If you try anyway, three failures within 10 seconds produce “Voice input is failing repeatedly and has been paused”, and Claude Code holds off until 10 seconds after the first of those failures. Anthropic lists a headless server, a remote shell with no audio passthrough, or a denied permission as the usual causes, so treat this message as a host problem rather than a network one. Before v2.1.202 only start-up failures counted toward the pause.
5. Space does nothing, or the transcript never arrives
Hold mode spots a held Space by watching for key-repeat events. If spaces keep piling up while you hold, dictation is off: run /voice hold. If one or two spaces appear and then nothing, dictation is on but hold detection is not firing, usually because key repeat is disabled at the OS level. Switch to /voice tap, which needs no key repeat, or bind voice:pushToTalk to a modifier combination such as meta+k in ~/.claude/keybindings.json; modifier bindings start recording on the first keypress. In tap mode, the first tap only starts recording when the prompt is empty, and a recording stops by itself after 15 seconds of silence or two minutes in total.
“Voice connection failed” means the recording never reached the transcription service, so check the network; since v2.1.200 a silent microphone reports “No audio detected” instead. “Voice stream error: WebSocket upgrade rejected with HTTP” followed by a status in the 400 range is a refusal rather than an outage: run /login to refresh a stale sign-in and look for a VPN, proxy or bot-protection service answering in place of the transcription service. Anthropic notes that native builds v2.1.229 through v2.1.231 kept showing “listening…” in this situation and only reported a connection failure after you stopped.
“No speech detected” means audio arrived but no words were recognized. Move closer to the microphone and check the language setting: dictation follows Claude Code’s language setting, supports 20 languages, and falls back to English for anything else. Anthropic already adds your project name and Git branch name as recognition hints.
6. Where /voice cannot work: dictate on your own computer instead
Some setups sit outside /voice by design: Claude Code signed in with an API key or a cloud provider, Claude Code on a remote host over SSH, a headless box, or WSL1. If you still want to speak your prompts there, the speech has to be recognized on the computer in front of you and typed into the terminal window.
IraVoice 1.2.2 does that on macOS 13+ on Apple silicon, Windows 10 or 11 (64-bit), and Linux (beta). It recognizes speech on-device with NVIDIA Parakeet after a one-time model download and types at the cursor of the focused terminal, so the same key works whether that terminal runs Claude Code locally, over SSH, inside tmux, or in a WSL tab. How Claude Code is signed in does not matter, because IraVoice never talks to Claude Code; it only types.
Know its limits before you rely on it. On a Mac or a Windows PC, IraVoice spells file and function names the way your code does, but it reads them from a Git project on the local computer, not from the host you reached over SSH. Inside WSL, the Windows app cannot see the Linux processes, so code names may not appear. On Linux, IraVoice is a beta and offers dictation without code names. It does not press Enter by default, so you still review the prompt before Claude Code acts.
- Focus the Claude Code prompt in the local terminal window.
- Hold Right Command (Mac), Right Ctrl (Windows) or Ctrl+Space (Linux) and speak.
- Release, read the text, then press Enter yourself; Esc cancels on Mac and Windows.