Voice Mode: Speaking Your Prompts Instead of Typing Them

📚 Series Navigation: The previous article 46 Development Configurations explained how to bootstrap environments to run Claude Code safely and efficiently. This article returns to a common task—how to speak your prompts, transcribing them into text in real time. Enabling /voice lets you hold the spacebar to speak prompts directly into the input field, which can be combined with manual typing. While it sounds complex, it takes a single command to configure, but has prerequisites; without meeting them, you will likely get stuck at the first step.

⚠️ Experimental feature, subject to changes. Commands, parameters, and version numbers in this article match the official documentation, but voice transcription is evolving. The actual behavior may vary depending on the prompts inside /voice on your machine.

While speaking prompts instead of typing them sounds efficient, voice input has historically been a novelty for developers—who type quickly anyway. Technical prompts containing variable names, function names, and snake_case tokens are often transcribed incorrectly by generic voice engines, creating typos that are more tedious to correct than typing. Technical notes referencing useEffect are easily transcribed as "U se if act" by typical voice inputs, prompting users to disable the feature.

Thus, trying Claude Code's dictation feature initially might come with skepticism. However, two aspects change this perspective: first, it is specifically tuned for technical vocabulary, recognizing terms like regex, OAuth, JSON, and localhost; second, it automatically feeds your active project name and git branch names as context clues to the transcriber, ensuring domain-specific jargon is recognized far more accurately than generic dictation tools.

This changes the utility. It is not meant to write code line-by-line, but to replace typing long descriptive prompts—sitting back to dictate "refactor the auth middleware to use the new token validation helper" is far easier than typing it. This article walks you through enabling and optimizing it, while addressing common roadblocks.

After reading this article, you will get:

• A clear understanding of what voice dictation is and where transcription occurs (not locally on your host)
• The critical prerequisite red line—it requires a Claude.ai account login; it is entirely unavailable when using API keys
• A compatibility table summarizing platform support (Mac, Windows, Linux, WSL, remote shells, VS Code)
• How to use the two recording modes (Hold vs. Tap) and their ideal use cases
• How to make dictation default on startup, configure dictation languages, and remap hotkeys
• A hands-on walkthrough with expected output: from enabling it to dictating your first prompt

---

01先搞懂：语音听写到底是个啥，转写在哪发生

Conclusion first: voice dictation translates your voice into text inside the prompt input field in real time—it is not a conversational "voice chat" with Claude; it simply replaces keyboard entry with speech.

Analogy: Real-time subtitles in a meeting. During an online call, you enable live captions; as you speak, text rolls across the screen. You are not chatting with the captions; they merely transcribe your audio into text. Claude Code's dictation acts similarly: you hold a key and speak, transcribing text into the prompt. The resulting text behaves identically to typed text—you can type amendments or press Enter to submit to Claude.

The official documentation describes it simply:

Speak your prompts in the Claude Code CLI instead of typing them. Your voice is transcribed in real-time to the prompt input, so you can mix voice and typing in the same message.

Notice the feature: "mix voice and typing in the same message." Transcribed text inserts at your cursor location, with the cursor positioned at the end of the insertion. This enables dictating description summaries while typing exact file names or functions. This integration is a primary reason it outperforms generic voice typing.

The next point is critical, dictating compatibility checks: your audio is not processed locally. From the docs:

Voice dictation streams your recorded audio to Anthropic's servers for transcription. Audio is not processed locally.

This means your voice is transmitted to Anthropic's servers to return text. This leads to three conclusions covered in subsequent sections: first, an active internet connection is required; second, you must authenticate using a Claude.ai account (so the server recognizes you); third, it is unsupported in remote sessions lacking microphone access (since audio is captured from the host terminal).

Finally, a helpful detail: transcription is free and does not consume credits. The docs state:

Transcriptions do not consume Claude messages or tokens, and do not count towards the limits shown in /usage.

In other words, dictating prompts does not draw from your API billing or subscription credits (billing detailed in Chapter 06). Verifying /usage after dictating several runs confirms that the limit remains unchanged. Use the feature without concern about burning through token credits; dictation is separate from message generation.

💡 Summary in one sentence: Voice dictation replaces typing with speaking, allowing you to combine transcribed and typed inputs; audio is processed on Anthropic's servers rather than locally, and transcription runs free of credit usage or /usage limits.

---

02 第一条红线：只认 Claude.ai 账户登录，用 API key 的直接开不了

This is the most important prerequisite—and where many developers get blocked initially.

Because audio streams to Anthropic's servers, verification is required. Therefore, you must authenticate via a Claude.ai account. The official documentation explicitly lists unsupported accounts:

The voice-to-text service is only available when you authenticate using a Claude.ai account. It is unavailable when Claude Code is configured to use Anthropic API keys directly, or via Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Voice dictation is also unavailable when your organization enforces HIPAA compliance.

In short—recall how you connected Claude Code in Chapters 04 and 05:

• Authenticated via Claude.ai account (Pro / Max subscriptions): ✅ Voice is supported.
• Using Anthropic API keys directly, or via Bedrock / Vertex / Foundry: ❌ Voice is unsupported.
• Organizations with HIPAA compliance active: ❌ Unsupported.

This is by design—transcription endpoints are integrated with Claude.ai account management; raw API channels do not support this capability.

To verify, simply try starting the mode: run /voice. If you use an API key, it throws a clear error message:

Voice mode requires a Claude.ai account

If you see this, do not troubleshoot microphone permissions; the authentication method is the issue. The solution: run /login to authenticate via a Claude.ai account. Machines running corporate API keys will throw this error when running /voice for the first time, which can be misdiagnosed as microphone driver failures—when it is simply an unsupported account type.

Authentication Method (Chapters 04 & 05)	Dictation Supported?
Claude.ai Account (Pro/Max Subscriptions)	✅ Yes
Anthropic API Key	❌ Errors with requires a Claude.ai account
Amazon Bedrock / Google Vertex / Microsoft Foundry	❌ Unsupported
HIPAA Compliance Enabled	❌ Unsupported

💡 Summary in one sentence: Dictation strictly requires a Claude.ai account login—it is unavailable for API keys, Bedrock, Vertex, Foundry, or HIPAA profiles; running /login resolves authentication blockers.

---

03 第二条门槛：得有本地麦克风，平台支持一张表说清

Once authenticated, the second requirement is hardware and access environment: although transcription occurs in the cloud, audio capture is performed by your local microphone. This dictates environment support.

Analogy: An active microphone plugged in. Captions require audio capture to transcribe; speaking at an isolated server without an input source yields nothing. Similarly, dictation requires local microphone access—meaning it is unsupported in environments where your physical microphone cannot link to the execution process.

The official documentation outlines this constraint:

Voice dictation also requires local microphone access, so it does not work in remote environments like Claude Code on the web or SSH sessions.

Platform / Environment	Support Status	Notes
macOS	✅ Native module	First /voice triggers system microphone prompts
Windows	✅ Native module	Allow microphone access for terminal in system settings
Linux	✅ Native module; falls back to arecord / rec on failure	If missing, /voice outputs installation commands
WSL	⚠️ Requires WSLg	WSL2 (Windows Store version) bundles WSLg; WSL1 lacks support, use native Windows instead
SSH Sessions	❌	Microphone is local, while session executes remotely
Claude Code on the Web	❌	Remote environment, no local microphone link (Chapter 11)
VS Code Extension	✅ (Requires Claude.ai account)	But VS Code Remote (SSH / Dev Containers / Codespaces) is ❌

Key integration points to notice:

Remote execution fails for the same reason. Whether running via SSH, Claude Code on the web (Chapter 11), or VS Code connected to a remote host—whenever the execution process runs remotely while your microphone remains local, voice is unsupported. The official guide notes this for 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 while the extension runs on the remote host.

WSL requires WSLg support. WSLg is Microsoft's GUI and audio integration for WSL2, bundled with WSL2 installed from the Windows Store on Windows 10/11. If you run WSL1 or lack WSLg, dictation fails—use native Windows shells instead.

Linux alerts you if recording packages are missing. Linux runtimes fall back to ALSA's arecord or SoX's rec if native modules fail; if both are missing, /voice prints the install command for your distribution (e.g., sudo apt-get install sox). Just run the suggested command.

💡 Summary in one sentence: Transcription runs in the cloud, but requires local microphone capture—meaning macOS/Windows/Linux native shells are supported, while remote contexts like SSH, Web, or VS Code Remote are unsupported; WSL requires WSLg, and Linux commands are output if audio utilities are missing.

---

04 两种录音模式：按住说，还是点一下说

With prerequisites met, let's enable it. Running /voice presents two recording modes—controlling how recording starts, stops, and whether it submits automatically.

Analogy: Walkie-talkie vs. voice recorder. A walkie-talkie requires holding a button to speak, stopping when released—this is "Hold mode." A voice recorder starts recording on a tap and stops on another tap, without requiring you to hold the button—this is "Tap mode." Choose the interaction model you prefer.

Mode	Trigger	Stop	Submission	Best Suited For
Hold (Default)	Hold Space	Release Space	Waits for Enter by default (auto-submit configurable)	Precise control over audio segments, pausing while thinking
Tap	Tap Space once to start	Tap Space again to stop	Auto-submits if transcript contains ≥3 words	"Speak and submit" workflow without holding keys

Hold Mode (Default): Walkie-Talkie Style

Hold mode is Push-to-Talk: hold Space to record, and release to stop. This is the default mode enabled by running /voice without modifiers.

A detail to notice: Hold mode has a brief "warm-up" period. Claude Code monitors key-repeat events to detect if the key is held, creating a slight delay where the footer displays keep holding... before displaying the wave graph. From the docs:

The first few key-repeat characters are typed into the input during the warm-up and are automatically deleted when recording activates. A single Space press still inputs a space, as hold detection only triggers on rapid key repeat.

In short: characters typed during warm-up are deleted automatically once recording starts, and a single tap on Space still inputs a normal space character—only holding the key triggers dictation, preventing interference with normal typing.

As you speak, transcribed text appears in the input field (dimmed until final verification), inserting at the cursor location upon release. Hold Space again to append more text. An example from the documentation:

> refactor the auth middleware to ▮
  # Hold Space, speak "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

By default, it does not submit automatically upon release, waiting for you to press Enter to allow reviews or manual additions. You can configure autoSubmit (Section 05) to submit automatically on release, provided the transcript contains at least three words.

Tap Mode: Voice Recorder Style

Tap mode uses a toggle: tap Space to start recording, speak, and tap Space again to stop and submit automatically. It has no warm-up delay, and you don't need to hold the key.

Enable it via /voice tap. Note that Tap mode requires a newer CLI version than Hold mode. From the docs:

Voice dictation requires Claude Code v2.1.69 or higher. Tap mode requires v2.1.116 or higher.

If /voice tap fails, run claude --version to check your CLI build.

Tap mode incorporates two protective guards:

• The first tap only triggers recording if the input is empty—preventing accidental recording triggers while typing prompts.
• Transcripts with fewer than three words are inserted but not submitted—preventing accidental single-word submissions.

It also stops automatically: after 15 seconds of silence or at the 2-minute limit.

Many developers prefer Tap mode once accustomed to it: the warm-up delay in Hold mode can be annoying, whereas Tap mode starts instantly and submits automatically, matching a "speak on thought" pace. However, Hold mode is better for inserting quick phrases or pausing while thinking. Test both to determine your preference.

💡 Summary in one sentence: Two interaction modes—Hold (Push-to-Talk) records while Space is held, inserting text on release; Tap (toggle recording, requires v2.1.116+) toggles on single taps, submitting automatically for transcripts of 3+ words.

---

05 三个调校：设成默认、改听写语言、换触发键

Configure these customizations once to optimize daily ergonomics:

Persistent Defaults: Configuring settings.json

Voice activation state persists across sessions, but to enable it by default, configure your user settings.json (Chapter 31):

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

Configure "release-to-submit" in the voice block using autoSubmit:

{
  "voice": {
    "enabled": true,
    "mode": "hold",
    "autoSubmit": true
  }
}

Language Support: Configuring Transcriptions

Voice dictation defaults to English—speaking other languages without configuring settings yields incorrect transcripts. The transcription engine uses the same language setting that configures Claude's output language, falling back to English if blank.

The transcription engine supports a fixed list of languages, which currently excludes Chinese (as of this writing, supported languages include Czech, Danish, Dutch, English, French, German, Greek, Hindi, Indonesian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Russian, Spanish, Swedish, Turkish, and Ukrainian). If you speak Japanese (ja) or Korean (ko), they are supported. If you primarily dictate in Chinese, note that native Chinese transcription is currently unsupported—check the /voice warnings on your machine for the active support list, as unsupported selections fallback to English.

Configure languages via /config or by writing directly to settings.json using language names or BCP 47 codes:

{
  "language": "japanese"
}

The docs add: if your configured language is unsupported for transcription, the voice module warns you and falls back to English for dictation—this only affects speech-to-text; Claude's output language settings remain unchanged.

Remapping Keybindings

The default key is Space for both modes. To remap it, configure voice:pushToTalk in ~/.claude/keybindings.json (Chapter 14):

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

A keybinding constraint specific to Hold mode is highlighted:

In hold mode, avoid binding a bare letter key like v because hold detection relies on key repeats, and the letter will be typed into the prompt during the warm-up.

In short: avoid mapping single letters as triggers in Hold mode (e.g., v)—because it relies on key-repeats, the character will leak into the input during the warm-up delay. To bypass the warm-up delay entirely, bind a modifier shortcut (like meta+k); modifier combinations activate recording on key-down without warm-up delays. Tap mode lacks warm-ups, making any keybinding acceptable.

💡 Summary in one sentence: Configure voice.enabled/mode in settings for persistent defaults (with autoSubmit for release-to-submit); dictation defaults to English, configured via language (Chinese is currently unsupported); remap triggers via voice:pushToTalk, avoiding single letters in Hold mode.

---

06 动手：从开启到说出第一句提示

Let's run a test. Ensure you are logged in via a Claude.ai account (Section 02) and running on a local machine (not remote SSH/Web). Run claude inside any scratch directory.

Step 0: Verify CLI Version (in host terminal)

claude --version

Expected: Version is ≥ 2.1.69 (or ≥ 2.1.116 for Tap mode). Upgrade if it is below this threshold, otherwise /voice commands are rejected.

Step 1: Start the session and enable voice

/voice

Expected: Triggers system microphone permission checks on first execution—on macOS, accept the system prompt. The footer prints:

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

Seeing Voice mode enabled confirms activation. hold indicates Push-to-Talk, and Dictation language: en specifies English transcription.

If it errors with Voice mode requires a Claude.ai account—refer to Section 02 and run /login to switch to a Claude.ai account login.

Step 2: Check the footer prompts

When the prompt input is empty, the footer displays hold Space to speak—indicating that holding the spacebar triggers capture.

Step 3: Hold the key and dictate in English

Hold Space and speak clearly in English (default language; do not dictate in Chinese):

list all files in the current directory

Expected: Transcribed text appears in real-time inside the prompt input (dimmed during processing); holding the key triggers keep holding... before displaying waveforms. Releasing the key finalizes the text:

> list all files in the current directory▮

The text matching your spoken audio indicates dictation works. It pauses without submitting, waiting for input edits.

Step 4: Append typed text and submit

Position the cursor at the end and type modifiers to verify the integration of voice and typing:

list all files in the current directory and show their sizes

Expected: Typed modifications append seamlessly. Press Enter to submit the query. This confirms that transcribed text behaves identically to typed text (Section 01).

Step 5: Test Tap mode (requires v2.1.116+)

/voice tap

Clear the input, tap Space once (do not hold), speak an English phrase of 3+ words, and tap Space again.

Expected: Tapping to stop transcribes and submits automatically. There is no warm-up delay, allowing you to compare the ergonomics of the two modes.

Step 6: Disable voice mode (Optional)

/voice off

Expected: The footer alerts that voice mode is disabled, prompt alerts vanish, and Space reverts to normal spacing behavior.

This walkthrough covers: "verifying builds -> granting mic permissions -> push-to-talk -> mixing inputs -> toggle-to-talk -> disabling voice." Future configurations simply involve updating settings for defaults, languages, or keymaps—the interaction flow remains the same.

💡 Summary in one sentence: The practice workflow takes six steps—verify version with --version, run /voice and grant permissions, hold Space to dictate in English, append typed text to verify integration, run /voice tap to test Tap mode, and disable via /voice off.

---

07 Summary

This article introduced voice dictation for Claude Code—in short, dictating long descriptive prompts replaces tedious typing, and the resulting text integrates natively with keyboard input.

Let's review the key points:

Prerequisite / Setting	Behavior	Key Point
What It Is	Real-time voice-to-text in the prompt input	Processed on Anthropic servers; doesn't draw from /usage limits
Supported Accounts	Requires Claude.ai Account	Unavailable for API keys, Bedrock, Vertex, Foundry, or HIPAA profiles
Supported Environments	Local shells work; remote sessions fail	Requires microphone access; SSH, Web, and VS Code Remote are unsupported
Enabling & Modes	Run /voice; supports Hold or Tap	Hold (Push-to-Talk) or Tap (requires v2.1.116+, auto-submits)
Customizations	Persistent defaults, remapping keys, and language settings	Defaults to English (Chinese is unsupported; Japanese/Korean are); remap trigger via voice:pushToTalk

You should now be able to: explain what voice dictation is, know that audio is processed in the cloud without credit cost, verify the Claude.ai account prerequisite before troubleshooting mic access, identify supported environments (local native only), select Hold or Tap recording modes, and write defaults, language overrides, and keybindings in settings. This input method reduces manual typing effort when describing long requirements—enabling it is optional, but you now know how to boot and customize it.

Returning to the initial bias against voice input—while it cannot write exact syntax, it is highly effective at transcribing dictated descriptive summaries. A tool does not need to handle everything; saving you effort in its specific niche makes it valuable.

---

The next chapter 48 "Comprehensive Practice: Building and Deploying a Project"—the first 47 chapters delivered tools and concepts: environment bootstrapping, prompt design, CLAUDE.md rules, MCP integration, subagent delegation, hooks, and Git workflows. While you know each component, have you ever combined them into a pipeline building a project from a scratch directory to deployment? The next chapter serves as a capstone: building a real project from scratch, connecting these tools to show how they operate together.

---

Recommended Reading

• Permission Configurations: How Loose or Strict Is Up to You
• Agent Skills: Equipping Claude with On-Demand Specializations
• Subagents: Delegating Tasks Instead of Handling Everything Yourself