← All guides

Voice modeSetup

Claude Code Voice Mode Not Working? How to Fix It

By Neo Zino - builder of ClockedCode·Updated September 12, 2026·9 min read

Claude Code's /voice dictation breaks down to five documented error messages, tested on 2.1.270 - and why it never works over SSH or in a container.

Made with DispatchSEO

Search "claude code voice mode not working" and half of what comes back is actually about the Claude phone app, which is a different feature from the /voice dictation Claude Code ships in the CLI. If you're chasing the CLI feature, the fix is one of five documented error conditions - a wrong account type, a denied microphone, unrecognized speech, a failed connection, or no microphone at all - and Claude Code's own troubleshooting docs now name each one by an exact message.

TL;DR: Run /voice and read the exact message it shows - code.claude.com's troubleshooting section names five of them, from "requires a Claude.ai account" to "No speech detected." If you're on SSH, a container, Claude Code on the web, or the VS Code extension's Remote mode, stop troubleshooting: none of those has a local microphone, so /voice cannot work there, full stop. And if the article you're reading talks about tapping a sound-wave icon or choosing a voice personality, you're reading about the Claude app, not Claude Code.

Two features share the name "voice mode" - only one of them is Claude Code's

Claude.ai's mobile, desktop, and web apps ship a voice mode of their own: tap a sound-wave icon, pick a voice, and have a spoken back-and-forth conversation. Claude Code's /voice is a different, much narrower feature - push-to-talk dictation that transcribes your speech into the prompt input so you can mix voice and typing in one message. They share a name and an owner, and nothing else.

The practical result: half of page 1 for this exact search - a Reddit thread, a couple of small blogs, a third-party add-on site - never actually distinguishes the two, so troubleshooting advice for the app's hands-free mode gets applied to the CLI's dictation feature and goes nowhere. Claude's own help center article on voice mode settles it under its Known Limitations: voice mode is "not compatible with Claude Cowork or Claude Code." If you're in the CLI and /voice is the command you typed, everything below is about your actual feature.

Run this checklist before you file anything

Before touching a single setting, confirm the basics Claude Code's own voice dictation requirements call out - most "not working" reports turn out to be one of these:

Voice dictation is authenticated-account-only by design: it needs Anthropic's speech-to-text service, which only runs for Claude.ai-authenticated sessions, never for direct API keys or cloud-provider auth. That single line explains a large share of "it just doesn't do anything" reports from teams on Bedrock or Vertex.

What each exact error message means, and how to fix it

Once the checklist above passes and /voice still misbehaves, the message it prints is specific enough to skip guessing. These are the exact strings from Claude Code's own error reference, in the order most setups hit them:

The No speech detected case is worth a closer look, because it's also the exact complaint behind a GitHub issue filed against Claude Code: a MacBook Air user with a confirmed-working microphone and terminal mic permission got "No speech detected" on every attempt, on Claude Code 2.1.63. It got closed as a duplicate rather than fixed as an open bug. The docs' current wording, "audio reached the transcription service but no words were recognized," is more specific than what shipped back then. That tracks with what the MCP server troubleshooting guide found in a completely different feature: Claude Code's error messages keep getting more specific release over release, and 2.1.63 is a long way behind the 2.1.270 this guide was tested on.

One that isn't in the table but shows up in a different shape: nothing happens when holding Space in hold mode. Hold detection relies on your terminal sending key-repeat events, so it can't detect a held key if your OS or terminal disables key-repeat. Switch to tap mode with /voice tap to sidestep the requirement entirely - tap once to start, speak, tap again to send, no held key involved.

Headless machines, SSH boxes, and containers: voice mode literally can't work there

There's no workaround here, because this isn't really a bug. Voice dictation needs a local microphone attached to the machine running Claude Code, and it explicitly does not work in Claude Code on the web or over SSH, because the audio never has anywhere to come from.

If you're on Linux and the native audio module can't load, Claude Code falls back to arecord (ALSA) or rec (SoX) - and if a WSL install specifically has no working recorder, it's almost always because only the ALSA backend got installed: run sudo apt install sox libsox-fmt-pulse instead of plain sox, since WSLg routes audio through PulseAudio rather than a /dev/snd device. On a genuinely headless server or a CI container like this one, there's no fix - there's no microphone to find, and as of Claude Code v2.1.195 the error message says so directly instead of asking you to install SoX you already have.

When to just type instead

If you're on a remote box, in a container, or your organization's managed policy has voice mode turned off entirely, dictation isn't coming back for that session - and that's fine. Claude Code's prompt input accepts typed and dictated text identically; nothing about a guide, a plan, or a multi-file edit depends on how the words got there. If a claude: command not found error is what's actually blocking you before you ever reach /voice, that's a separate, more basic problem worth ruling out first.

Persisting your preferred mode also avoids re-running /voice every session - set it once in your settings.json:

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

Honest limits

Everything in the error checklist above is Claude Code's own documented behavior as of the docs I read while writing this, checked against a live install on 2.1.270. The headless-environment test is real and reproduced on this exact build sandbox, not assumed from the docs' wording. What I can't verify from here: exact behavior on Windows-native builds, and whether your specific terminal emulator's key-repeat settings match the ones I could test. If your Claude Code version is meaningfully older or newer than 2.1.270, run claude doctor before assuming these exact strings still match what you're seeing - error text is exactly the kind of thing that drifts between releases.

FAQ

Why does Claude Code say "No speech detected" when I use /voice?

Your recording reached Anthropic's transcription service but no words were recognized in it. Speak closer to the microphone, cut background noise, and check /config to confirm your dictation language matches what you're actually speaking - a mismatched language is a common silent cause.

Is Claude Code's voice mode the same feature as the Claude app's voice mode?

No. Claude Code's /voice is CLI-only push-to-talk dictation that requires a local microphone and a Claude.ai account. The Claude app's voice mode (mobile, desktop, web) is a separate hands-free conversation feature, and Claude's own help center lists Claude Code as explicitly not compatible with it.

Why doesn't voice mode work over SSH, in a container, or on Claude Code on the web?

Voice dictation streams audio from a local microphone, and none of those environments have one attached to the process running Claude Code. On this exact build sandbox - a headless Linux container - there's no SoX, no ALSA recorder, and no /dev/snd device at all, which is precisely the condition the docs describe.

How do I fix "Microphone access is denied" in Claude Code?

Grant your terminal app microphone permission in your OS privacy settings - System Settings -> Privacy & Security -> Microphone on macOS, Settings -> Privacy & security -> Microphone on Windows - then run /voice again. If your terminal isn't even listed on macOS, reset its permission state with tccutil reset Microphone com.apple.Terminal (swap in your own terminal's bundle id) and relaunch it so a fresh prompt appears.

What do I do if none of these fixes work?

Confirm the basics first: a real microphone, a Claude.ai account (not an API key or Bedrock/Vertex/Foundry auth), and a local session rather than SSH or the web. If everything checks out and /voice still fails, it's likely version-specific - run claude doctor for a full setup check and compare your Claude Code version against the fixes this guide cites.

One feature, one command, no ambiguity left

/voice either works because the account, the microphone, and the environment all check out, or it prints one of five specific messages telling you which one doesn't - Claude Code stopped failing silently here a while ago. The only case with no fix is architectural: no local mic means no dictation, on this machine, ever. Past that, ClockedCode's own settings.json generator can set your preferred voice mode alongside the rest of your config in one pass, so you don't have to remember the /voice incantation every time you sit down.