Why is Claude Code voice dictation not working?

Claude Code's voice dictation is turned on with /voice. When it fails, the cause is often a setting rather than a bug, and the error text does not always name it. Check four things in this order: your sign-in, any API key in your environment, the microphone permission for your terminal, and whether the session has a microphone at all. This page is part of our guide to voice input for Claude Code and AI coding tools, which covers the other tools too.

"Unknown command: /voice" means you are not signed in with claude.ai

If /voice reports an unknown command, Claude Code is not using a claude.ai sign-in. The docs say that /voice is available only while a claude.ai account is your active sign-in ¹. Run /login, sign in with your claude.ai account, and then run /voice again.

If you are already signed in and still see the message, something else is taking precedence. Go to the next section.

An API key or provider setting overrides your sign-in

A claude.ai sign-in is not the only way Claude Code can authenticate. The docs name ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, an apiKeyHelper setting, and third-party providers such as Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry. When one of these is in use, it takes precedence over a claude.ai sign-in ². Speech-to-text is not available in that setup, so /voice does not work.

To fix it:

1. Unset ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN in the shell where you start Claude Code, and remove any apiKeyHelper or provider setting that applies to it.
2. Quit Claude Code and start it again.
3. Run /login if it asks, then run /voice.

If you need the API key for other tools, start Claude Code from a separate shell that does not set it.

On a Mac, the terminal needs microphone permission

Dictation records through the terminal app you use, so that app needs microphone access. On a Mac, if you denied the macOS microphone prompt, open System Settings, then Privacy & Security, then Microphone, and turn on your terminal app. The docs then say to run /voice again ³. On Windows, the same step is Settings > Privacy & security > Microphone, with microphone access for desktop apps turned on.

If you changed the setting while the terminal was open and it still fails, quit the terminal with Cmd+Q. Closing its windows is not enough, and macOS does not prompt a process that is already running ⁴. Reopen the terminal, start Claude Code, run /voice, and allow the prompt.

If your terminal does not appear in the Microphone list at all, the docs describe a reset of its permission state. That reset can affect other apps, so read the troubleshooting section of the Claude Code docs before you run it.

Hold-to-talk needs key-repeat, so tap mode is the fallback

Hold mode is the default. You hold Space, Claude Code records while the key is held, and it stops when you let go. It detects the held key by watching for key-repeat events from the terminal. If key-repeat is turned off at the operating system level, the hold is not detected ⁵.

The symptom is specific. If you hold Space and only one or two spaces appear, then nothing, dictation is on but hold detection is not triggering. Run /voice tap instead. In tap mode, one tap starts recording and a second tap sends. Tapping Space types a space when the prompt already has text, because the first tap only starts recording when the input is empty. Clear the input first.

A session with no local microphone cannot dictate

Voice dictation needs a local microphone. It does not work in cloud sessions or SSH sessions ⁶. If you run Claude Code on a remote server, /voice will fail there, whatever you change on your laptop. Run Claude Code on the computer that has the microphone you are speaking into.

A recent update can break dictation that worked before

Version changes can break a setup that used to work. A GitHub report from March 2026 says voice dictation in Claude Code 2.1.83 activated but never transcribed, and that rolling back fixed it for that user ⁷. The issue was closed as a duplicate of other reports of the same problem. Treat it as a pattern to check rather than a diagnosis of your install. Note your current version before you change anything, so you can compare the result.

When none of these fixes the problem

Two more checks cover the rest of the common cases:

• Repeated failures pause dictation. Claude Code pauses after three failures within 10 seconds ⁸. Wait for the pause to end, check the microphone and its input level, then try again. Pressing the key repeatedly does not help.
• The microphone is muted or not the default. Select the microphone you use as the system's default input device, and check that its input level is not near zero, as the docs advise.

If /voice still fails, you do not have to wait for a fix. A system-wide dictation app types into the focused field, and it can work in the terminal where you run Claude Code. Compare the options in our guide to the best dictation tool for Claude Code. For a broader view of how Claude handles speech, read dictation in ChatGPT and Claude and our answer on dictation languages in Claude. Hold-to-talk is also called push-to-talk in other tools.