voicemode

Security

• New runtime floors so pip and uvx installs get the 9.0.0 security fixes too: certifi>=2026.10.19 (critical CA fix), uv>=0.13.4 and pyjwt>=2.15.0. (VM-2492)
• fastmcp>=3.4.10 fixes GHSA-7xgj-8392-5q4r (component authorization skipped on direct calls), and opentelemetry-api>=1.45.1 fixes GHSA-xcq7-p3pf-p88h (unbounded tracestate parsing).

Installation

Quick Start (Recommended)

# Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install VoiceMode and configure services
uvx voice-mode-install

# Add to Claude Code MCP
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

Alternative: Direct Installation

# With UV
uv tool install voice-mode

# With pip
pip install voice-mode==9.0.1

For detailed documentation, visit https://getvoicemode.com

Added

• conch(action="heartbeat") now reports granted and claim_window_remaining, so a queued remote agent sees its grant without an extra status call. (VM-2078)
• voicemode service install mlx-audio warns when the espeak-ng data path is 160+ characters, which crashes the server on the first Kokoro request. (VM-2338)

Changed

• Voice names resolve completely or fail: a voice= (or a VOICEMODE_VOICES default) the resolver cannot place is now an error naming the cause, not silent Alloy. See Migration. (VM-1901)
• The converse tool description is cut from ~2,400 to ~190 tokens; the MCP connect cost of the default tool set falls from ~4,400 to ~2,170 tokens. (VM-2442)
• listen_duration_max is unset in the converse schema by default, so your VOICEMODE_DEFAULT_LISTEN_DURATION sets the listening ceiling. (VM-2442)
• The transcript echo (ASSISTANT/USER (voicemode) blockquotes) is gone from the tool description and the skill; the Talk app already shows the conversation. (VM-2442)
• One VoiceMode skill: converse, impressions and voicemode-dj are folded into voicemode, with the detail in its references. (VM-2442)
• STT on mlx-audio needs no model setting: with VOICEMODE_STT_MODEL unset it is sent mlx-community/whisper-large-v3-turbo-asr-4bit instead of whisper-1. (VM-2342)
• With VOICEMODE_WHISPER_LANGUAGE=auto, mlx-audio is sent no language and detects it; whisper.cpp still gets auto. (VM-2342)
• STT 4xx get their own listen_and_transcribe error_kind and ask_turns stop reason: stt_model_not_found (HTTP 404) and stt_request_rejected (other 4xx). (VM-2342)
• mlx-audio STT no longer drops whisper's "" / "." / "..." silence segments (the old patch did); default whisper.cpp installs are unaffected. (VM-2338)
• mlx-audio answers clients that omit response_format with ndjson, not json; converse and impressions always send it. (VM-2338, VM-2346)
• The mlx-audio install result has a warnings list in place of its patch key. (VM-2338)

Removed

• converse(conch_mode=...) and VOICEMODE_CONCH_MODE: callback mode never delivered its turn and could wedge the conch queue. See Migration. (VM-2078)
• timeout from the converse MCP schema (no effect since LiveKit left); passing it is now a validation error. The CLI keeps it. See Migration. (VM-2442)
• VoiceMode Connect docs and the voicemode-connect skill: the product was abandoned. voicemode connect auth stays for now; its removal is VM-2314. (VM-2290)
• The bundled mlx-audio server.py patch: upstream serves response_format natively since 0.4.4. (VM-2338)

Fixed

• All 67 Kokoro voices work in converse again, not just a 7-name whitelist; a voice no configured endpoint serves still fails loudly. (VM-2190)
• voicemode service install mlx-audio installs current mlx-audio again: the pin is now mlx-audio>=0.5.7,<0.6 (was >=0.4.3,<0.4.4). (VM-2338)
• STT: an HTTP 4xx is no longer reported as "STT service connection failed"; a 404 names the model and endpoint and points at VOICEMODE_STT_MODELS. (VM-2342)
• Impressions voice-profile transcription asks the STT server for JSON, so it works on mlx-audio 0.4.4 and later. (VM-2346)
• The docs no longer tell assistants to pass their own listening limit, which silently overrode your VOICEMODE_DEFAULT_LISTEN_DURATION and cut you off. (VM-2099)
• The parameter reference is one document for assistants and the docs site, and listen_duration_max / listen_duration_min have real descriptions. (VM-2099)
• A silent converse(hold_conch=true) no longer holds the channel indefinitely: the hold is kept only when the turn spoke. (VM-2045)
• Every conch grant is covered by the VOICEMODE_CONCH_GRANT_TTL self-heal, so an unclaimed grant can no longer wedge the queue. (VM-2078)
• conch give / summon to a session not in the queue grants only on a confirmed nudge; otherwise it returns granted: false and the o

Fixed

Cancelling voice no longer kills your session (VM-2015)

Pressing ESC during a voice call used to leave everything broken behind you. This one has been with us for months and survived an earlier attempt at a fix (VM-1026) — it's properly fixed now.

• ESC wedged the connection, then killed the server — the cancel looked clean, but the next converse() call got no response at all and the MCP server then exited on its own, taking voice down until you restarted it. CancelledError is now handled at the boundary the MCP SDK expects, so a cancel unwinds one request instead of the whole server.
• The microphone kept recording after a cancel — recording ran on a thread that couldn't be interrupted, so it ran on to listen_duration_max and transcribed audio nobody asked for. It's now cooperatively cancellable and releases the mic in under a second (measured 0.4s vs 17.5s on a 20s limit), including when the client goes away without cancelling at all — agent killed, terminal closed, broken pipe.

Other fixes

• A stuck conch grant could block every waiter forever (VM-1967) — a WAIT-mode call cancelled mid-wait left its queue entry registered, and once granted it deadlocked everyone behind it while voicemode conch status still reported the conch free. Queue entries are now deregistered on every exit path, an unclaimed grant self-heals after VOICEMODE_CONCH_GRANT_TTL (default 30s), and conch status distinguishes "free" from "granted but unclaimed".

Added

• Wall-clock time widget for converse() results (VM-1961) — the opt-in time_in_response param / VOICEMODE_TIME_IN_RESPONSE env var (default off) appends the local time to every converse() return as a trailing | Widgets: time HH:MM:SS, so the agent has a clock instead of guessing. Text-only, never spoken. See converse-parameters.md.

• Saved STT recordings are now linked from the conversation log (VM-4) — with VOICEMODE_SAVE_AUDIO on, stt log entries recorded audio_file: null, so a transcript couldn't be tied back to its recording. The filename is now logged for both single listens and survey turns, matching what TTS entries already did. No schema change.

Removed

• ~2,300 lines of confirmed-dead code removed (VM-1811) — code with zero live callers, verified by AST import-map and caller-grep across the package. No behaviour change. Includes 7 orphan modules (all of tools/sound_fonts/ among them), the legacy cli click group, the expired _env_deprecation.py machinery, SecretPathMiddleware, assorted dead helpers and shims, and the direct websockets dependency (still available transitively via fastmcp).

Installation

Quick Start (Recommended)

# Install UV package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install VoiceMode and configure services
uvx voice-mode-install

# Add to Claude Code MCP
claude mcp add --scope user voicemode -- uvx --refresh voice-mode

Alternative: Direct Installation

# With UV
uv tool install voice-mode

# With pip
pip install voice-mode==8.12.0

For detailed documentation, visit https://getvoicemode.com

Added

Native Windows support — no WSL required (#232)

• The MCP server, converse, and the CLI now run natively on Windows 11: portable file locking (voice_mode/file_lock.py), safe PID liveness probes via psutil, a dead-stream stall backstop in the recording loop, and a Windows-safe VOICEMODE_DEBUG. No behavior change on Linux/macOS; works with local or remote OpenAI-compatible STT/TTS endpoints.

Multi-voice sequences and voice surveys — converse grows turns[]

• Multi-voice turns[] (VM-1772) — one converse call speaks an ordered multi-voice script with no synthesis dead-air (turn N+1 synthesizes while N plays). Per-turn voice, pause_after_ms (default 150 ms), tts_instructions, speed. CLI: repeatable --say 'VOICE:TEXT' or --script FILE|-. The scalar message/voice path is unchanged.
• Surveys — the ask verb (VM-1775) — a turn can speak a question and collect the spoken reply, so a multi-question survey runs in one call. Returns an index-aligned JSON survey result, so a partial run still shows exactly which questions were answered; each reply is logged the instant it's captured. Full per-turn control-channel support plus spoken "repeat" / "wait" / "break". CLI --ask exits 0 on completion, 3 on a partial.
• "Heard you" cue (VM-1859) — opt-in ack plays a short content-free cue the moment an ask turn captures a reply, and stays silent on a timeout — audible contrast between captured and missed. Default off; enable per turn, call-wide, or with --ack.
• Survey conventions (VM-1859) — agents are now instructed to announce the question count up front and acknowledge collected answers at the top of the next call.

Control channel — transport buttons for in-flight speech

• pause / resume / stop (VM-1676) — a local-only socket into the running server lets a Stream Deck key, media key, or voicemode control {pause|resume|stop} act on the utterance being spoken without going through the agent; a stop returns a clean [control: stop] marker so the assistant continues in text. Off by default (VOICEMODE_CONTROL_CHANNEL_ENABLED=true). See docs/reference/control-channel.md.
• skip-back (VM-1685) — CD-style replay: first press restarts the current utterance, further presses step back through a bounded history buffer (VOICEMODE_HISTORY_BUFFER_SIZE, default 8). Replays cached audio only — no new agent turn, no STT, no model call. Pause now frees the provider connection (resume plays the buffered remainder), and a status query reports now-playing + buffer position.
• skip-forward (VM-1739, VM-1754) — the universal "move on" button: pressed while the assistant speaks, it cuts the utterance and hands you the mic; pressed while you speak, it ends the recording immediately and transcribes what was captured — a manual end-of-turn and a reliable VAD fallback. Lands in ~200 ms.

Other

• voicemode reconnect (VM-1727) — heal a dropped voicemode MCP server from a single CLI call: drives Claude Code's /mcp reconnect flow on the agent's own tmux pane, fails loud rather than sending blind keystrokes, distinct exit codes per outcome.

Changed

• Media-key Next now barges instead of stopping (VM-1742) — the Hammerspoon binding sends skip-forward: cut the assistant and take the mic. Point ~/.hammerspoon/init.lua at scripts/hammerspoon/voicemode-media-keys.lua.
• Previous media key now replays (VM-1919) — the Hammerspoon binding's Previous handler is wired to voicemode control skip-back (it was a notice-only stub pending VM-1685): first press restarts the current utterance, further presses step back.
• Held pause self-heals after 5 minutes, not 30 seconds (VM-1853) — pause-and-walk-away now survives; tune with VOICEMODE_CONTROL_PAUSE_TIMEOUT.

Security

• *Control channel hardened following adversarial review (VM-1688)