Setup · v0.4.0
Set up text-to-speech for Claude Code.
Three steps to hear Claude Code speak on Windows. The free path needs no account and no API key.
Install in three steps
- 01
Install on Windows
Download the installer from GitHub Releases and run it. Windows only — there is no macOS or Linux build yet.
- 02
Pick a voice
On first launch, add an ElevenLabs or Mistral API key in settings — or skip keys entirely and use a Piper neural voice, downloaded in-app, or the built-in Windows voice. The free path needs no account.
- 03
Turn on attention alerts
Companion TTS installs a Claude Code Notification hook so it can speak up the moment a session blocks on you — an approval prompt, a question, or a plan awaiting review.
How it works
Rust watches ~/.claude/projects/**/*.jsonl — the transcript files Claude Code writes as it works — and tails them incrementally, so noise never reaches the UI.
Claude's messages become speakable phrases: paths shrink to basenames, code blocks summarize, markdown melts away. They queue and play through the provider chain in order.
Synthesis happens in Rust, so API keys stay native-side and never enter a webview.
Pre-existing sessions are never narrated. The tailer primes at end-of-file, so it only speaks what happens after it starts watching.
Questions
- What does the Notification hook change?
- It adds a hook entry to ~/.claude/settings.json that appends notification events to a local file the app tails. Your original settings are backed up once to settings.json.companion-bak, and nothing else is touched.
- Does it send my transcripts anywhere?
- Only the text being spoken goes to the TTS provider you configured. With a Piper voice or the Windows voice, nothing leaves your machine at all.
- Do I need an API key?
- No. Piper runs fully offline as in-process ONNX inference, and the Windows on-device voice is always available. API keys are only needed for the ElevenLabs and Mistral cloud voices.
- Does it work on macOS or Linux?
- Not yet. Companion TTS is Windows-only for now — it runs on the system WebView2 via Tauri v2.
- Which languages are supported?
- English only. The six Piper voices cover en-GB and en-US.
- Why GPL-3.0?
- The offline Piper provider compiles in espeak-ng (GPL-3.0) for phonemization, which makes distributed builds a GPL combined work.