voicemode

name voicemode description Voice interaction for Claude Code. Use when users mention voice mode, speak, talk, converse, voice status, or voice troubleshooting. First-Time Setup If VoiceMode isn't working or MCP fails to connect, run: /voicemode:install After install, reconnect MCP: /mcp → select voicemode → "Reconnect" (or restart Claude Code). If Claude Code prompts you for permission on voicemode:converse or voicemode:service , see references/permissions.md for the one-time allow-list setup. VoiceMode Natural voice conversations with Claude Code using speech-to-text (STT) and text-to-speech (TTS). Note: The Python package is voice-mode (hyphen), but the CLI command is voicemode (no hyphen). When to Use MCP vs CLI Task Use Why Voice conversations MCP voicemode:converse Faster - server already running Service start/stop MCP voicemode:service Works within Claude Code Installation CLI voice-mode-install One-time setup Configuration CLI voicemode config Edit settings directly Diagnostics CLI voicemode diag Administrative tasks Usage Use the converse MCP tool to speak to users and hear their responses: # Speak and listen for response (most common usage) voicemode:converse( "Hello! What would you like to work on?" ) # Speak without waiting (for narration while working) voicemode:converse( "Searching the codebase now..." , wait_for_response= False ) For most conversations, just pass your message - defaults handle everything else. Use default converse tool parameters unless there's a good reason not to. Timing parameters ( listen_duration_max , listen_duration_min ) use smart defaults with silence detection - don't override unless the user requests it or you see a clear need. Defaults are configurable by the user via ~/.voicemode/voicemode.env . Parameter Default Description message required Text to speak wait_for_response true Listen after speaking voice auto TTS voice -- must be lowercase (e.g. af_river , not AF_River ) Voice name rule: If you specify a voice , it MUST be lowercase with underscores. Kokoro rejects capitalized names like AF_River with a 400 error. Valid examples: af_river , af_sky , bm_daniel , bf_emma . The prefix encodes language+gender: af_ = American female, am_ = American male, bf_ = British female, bm_ = British male. When in doubt, omit voice entirely -- auto-select picks a working default. Voice discovery for apps and agents: read the voice://voices MCP resource for a structured JSON list of available voices (with voice://voices/{provider} for per-backend filtering). The voice_registry tool returns the same data as prose for the LLM mid-conversation. Both share the underlying enumerator so they never drift. See voices resource reference . Persona discovery: voice IDs from voice://voices map to character profiles on disk at ~/.voicemode/voices/<name>/README.md (grouped voices: <group>/<name>/README.md ; index at ~/.voicemode/voices/PERSONAS.md ). Read that README before speaking in character — who they are, how they speak, sample lines. Not every voice has one yet; fall back to the bare voice if absent. For all parameters, see Converse Parameters . Best Practices Narrate without waiting - Use wait_for_response=False when announcing actions One question at a time - Don't bundle multiple questions into a single spoken turn. The exception is a survey (the turns param): it asks several questions in one call but still delivers them one turn at a time, listening after each — see Surveys (multi-turn asks) . Check status first - Verify services are running before starting conversations Let VoiceMode auto-select - Don't hardcode providers unless user has preference First run is slow - Model downloads happen on first start (2-5 min), then instant Surveys (multi-turn asks) The converse turns param runs a survey : several questions asked in a single call, delivered one turn at a time (speak, listen, record, advance), pipelined so turn N+1 is synthesized while turn N plays — no synth dead-air. This is the sanctioned exception to "one question at a time": you're still asking one question per spoken turn, just scripting the whole sequence up front. Because the survey advances to the next scripted question automatically, without reacting to each answer , the user can't otherwise tell whether they were heard or the script just moved on. Make multi-turn legible: Announce the count up front. Open the survey with a leading say turn that states how many questions are coming — e.g. "I've got 3 quick questions." This is the signal that a multi-turn survey is running. Acknowledge at the top of the NEXT call. Content-aware acknowledgment ("got it — chicken, twice a week, no allergies") can't be pipelined mid-survey without reintroducing dead-air, so it belongs at the top of your next converse call , before you move on. Recap the answers you collected so the user knows they landed. Keep it short. ≤ ~7 ask turns per survey; give each a sensible listen_duration_max (30–45s for normal questions). Voicemode echo (default ON) Some hosts (e.g. newer Claude Code) collapse MCP tool calls — voice turns vanish from the visible transcript. Unless requested otherwise, default to voicemode echo: print each voicemode:converse exchange as Markdown blockquotes so it stays readable on screen. > **ASSISTANT (voicemode):** <message arg passed to converse> [voicemode:converse tool call] > **USER (voicemode):** <captured user message> Speaker first in caps; (voicemode) is the channel tag. Order matters. Write the ASSISTANT blockquote before the voicemode:converse tool call, in the same response that issues it — so the user can read along while the audio plays (and recover the message if they miss part of it). Write the USER blockquote in your next response, after the tool result returns. Don't batch both echoes after the call. ASSISTANT echo: always , including wait_for_response=false (speak-only narration still produces visible content that would otherwise vanish). USER echo: only when a user message was captured (skip on wait_for_response=false , empty result, or transcription failure — there is nothing to echo). Assistant echo: verbatim by default — the exact string passed to message , not paraphrased or reformatted. Reasons: least-surprising for the reader + diagnostic value when comparing printed text to spoken audio. User echo: verbatim and full — exact words, no truncation; rewriting or shortening risks distorting intent. Visual aids (lists, tables, code) belong AFTER the blockquote, not inside it. The blockquote stays a clean verbatim copy of what was spoken; richer formatting can follow as separate prose. Don't double-echo: if a sentence already appears as visible prose in the same response, don't also blockquote it. Disable on request — canonical phrase: "disable voicemode echo" . Stop echoing for the rest of the session and honour the same phrase if it appears in the user's startup context (some hosts already render voice tool calls inline, where echoes would double up). Parallel Tool Calls (Zero Dead Air) Eliminate dead air by sending voice and action calls in the same response : # FAST: speak + act in parallel (all fire concurrently) voicemode:converse("Checking that now.", wait_for_response=False) Bash("git status") Agent(prompt="Research X", run_in_background=True) # SLOW: sequential — unnecessary delay between speech and action voicemode:converse("Checking that now.", wait_for_response=False) # ... waits for TTS to finish ... Bash("git status") Then report results in the next response: voicemode:converse("Here's what I found: ...", wait_for_response=True) Scenario Approach Why Announce + do work Parallel No dependency between speech and action Announce + spawn agent Parallel Agent runs in background anyway Check result then report Sequential Need result before speaking Listen for response Sequential wait_for_response=True blocks until user speaks Key insight: Wall-clock time = longest call, not the sum. All tool types (MCP, Bash, Agent, Read) can be mixed in one response. Handling Pauses and Wait Requests When the user asks you to wait or give them time: Short pauses (up to 60 seconds): If the user says something ending with "wait" (e.g., "hang on", "give me a sec", "wait"), VoiceMode automatically pauses for 60 seconds then resumes listening. This is built-in. Longer pauses (2+ minutes): Use bash sleep N where N is seconds. For example, if the user says "give me 5 minutes": sleep 300 # Wait 5 minutes Then call converse again when the wait is over: voicemode:converse( "Five minutes is up. Ready when you are." ) Configuration: The short pause duration is configurable via VOICEMODE_WAIT_DURATION (default: 60 seconds). Transport controls (media keys & Stream Deck) While a converse is live, VoiceMode exposes a control channel — drive it with voicemode control pause | resume | stop | skip-forward | skip-back . You can wire these to physical buttons so the human can pause/barge/replay without typing: Stream Deck (or any tool that runs a shell command): bind a button straight to voicemode control skip-forward etc. No extra dependency — it shells out to the CLI directly. macOS media keys (▶❙❙ / ⏭ / ⏮): routed through a Hammerspoon eventtap ( scripts/hammerspoon/voicemode-media-keys.lua ) that only grabs the keys while a converse is live, so music is untouched otherwise. Enabling: Set VOICEMODE_CONTROL_CHANNEL_ENABLED=true in ~/.voicemode/voicemode.env (server binds ~/.voicemode/control.sock for the converse turn). For media keys: install Hammerspoon, load the config from ~/.hammerspoon/init.lua , grant Accessibility , and keep Hammerspoon running — make it a login item. The eventtap only exists while Hammerspoon is running; if it's not, the keys silently pass through to Music/Spotify and VoiceMode never sees them (no error — they just do nothing). A working Stream Deck with dead media keys = Hammerspoon isn't running. Quick check: pgrep -x Hammerspoon . Setting this up for a user? Use the media keys agent runbook — a step-by-step procedure for the assistant to do the setup end-to-end, flagging the one step (the Accessibility grant) that needs the human. Full reference (ownership model, skip-back history buffer, raw-socket protocol): docs/reference/control-channel.md . STT Recovery - Manual Transcription If Whisper STT fails but the audio was recorded successfully, you can manually transcribe the saved audio file: # Transcribe the most recent recording whisper-cli ~/.voicemode/audio/latest-STT.wav # Or check if file exists first (safe for inclusion in automation) if [ -f ~/.voicemode/audio/latest-STT.wav ]; then whisper-cli ~/.voicemode/audio/latest-STT.wav fi Requirements: Audio saving must be enabled via one of: VOICEMODE_SAVE_AUDIO=true in ~/.voicemode/voicemode.env VOICEMODE_SAVE_ALL=true (saves all audio and transcriptions) VOICEMODE_DEBUG=true (enables debug mode with audio saving) How it works: VoiceMode saves all STT recordings to ~/.voicemode/audio/ with timestamps The latest-STT.wav symlink always points to the most recent recording If the STT API fails, the recording is still saved for manual recovery This lets you recover the user's speech without asking them to repeat When to use: STT service timeout or connection failure Transcription returned empty but user definitely spoke Need to verify what was actually said vs. what was transcribed See also: Troubleshooting - No Speech Detected Check Status voicemode service status # All services voicemode service status whisper # Specific service Shows service status including running state, ports, and health. Reconnecting after a mid-session drop If voice drops mid-session ( -32000 Connection closed ) — or the server failed to register its tools at launch — the voicemode MCP tools vanish, so recovery can't be an MCP tool. Bash and tmux survive, so heal it in one Bash call : voicemode reconnect This runs the whole /mcp reconnect dance on your own pane ( $TMUX_PANE ): opens the menu, finds the voicemode server by name (not a fragile Down-count), navigates to it by reading the cursor, hits Reconnect only if it's failed, polls until it's connected, then prints the exact ToolSearch line to reload the converse schema. It fails loud rather than sending blind keystrokes if the screen isn't what it expects. Must run inside tmux (it drives the pane via tmux). After it prints RESULT: reconnected , run the ToolSearch select:… line it echoes to reload the tool schema, then resume conversing. RESULT: reconnected # exit 0 — was failed, now reconnected RESULT: already-connected # exit 10 — nothing to do (benign no-op) # 11 not-found · 12 timeout · 13 not-in-tmux · 1 error Useful flags: --pane <id> (drive another pane), --server <substr> (default voicemode ), --timeout <s> (default 75), --dry-run (report, send no keys). Fallback — drive /mcp by hand (older Claude Code, or if voicemode reconnect ever fails loud on an unfamiliar menu): the step-by-step manual walk lives in ~/.slipbox/voice-self-reconnect.md — open /mcp , read the list with capture-pane , navigate to voicemode, hit Reconnect, wait ~1 min, reload the schema. Installation # Install VoiceMode CLI and configure services