Skip to main content
This page will cover voice input and output. Voice brackets the turn rather than changing it: speech-to-text feeds the same message-building path as typed input, and text-to-speech reads back the reply after the output guard has run, so a guardrail refusal is spoken too rather than silently dropped. Push-to-talk is bound to F11, started with the --voice flag, or toggled with the /voice command. Backends are pluggable on both sides. Locally, faster-whisper handles STT and Piper handles TTS; install them with uv sync --group voice-local. Cloud backends cover OpenAI, Deepgram, and ElevenLabs, and the config names the environment variable holding an API key, never the key itself. The page will cover the voice section of settings.yaml (was voice_policy.yaml) in full. It is off by default, and the presence of the section does not enable it, so you must set enabled: true and install your chosen backends. Settings include per-direction backend and model selection, capture settings with a hard cap on one utterance as a runaway-microphone guard, a cap on synthesized text length, and fail_open, which degrades to text with a notice rather than crashing when a backend fails. Voice is interactive only; the headless one-shot path stays text-only.
This page is in progress. The shipped voice section is fully commented and is the best reference until it lands. Legacy split voice_policy.yaml files still resolve.
See Terminal UI for the push-to-talk binding, Commands for /voice, and Configuration for how the voice section resolves.

Related topics

InstallationFlavoursSlash commandsAgent configurationCommand line reference