punt-vox
Voice for your AI coding assistant.
When Claude Code finishes a task, hits an error, or needs your approval --- you hear it. No need to watch the terminal. Keep working; your assistant will tell you what happened.
Platforms: macOS, Linux
Hear It
Real samples generated by vox with ElevenLabs v3. The first three are the same recap with different /vibe moods --- expressive tags change how the voice sounds without changing the words.
| Sample | Vibe | Voice | |
|---|
| Task recap | neutral | sarah | listen |
| Same recap | [excited] | sarah | listen |
| Same recap | [weary] [sighs] | sarah | listen |
| Task complete | neutral | matilda | listen |
Quick Start
curl -fsSL https://raw.githubusercontent.com/punt-labs/vox/4ced624/install.sh | sh
Restart Claude Code, then:
/vox y # hear when tasks complete or need input
/recap # spoken summary of what just happened
Manual install (if you already have uv)
uv tool install punt-vox
vox install
vox doctor
Verify before running
curl -fsSL https://raw.githubusercontent.com/punt-labs/vox/4ced624/install.sh -o install.sh
shasum -a 256 install.sh
cat install.sh
sh install.sh
Configure providers
The Quick Start gets you running with the OS's built-in voice — say on macOS, espeak-ng on Linux. For a natural-sounding voice, configure any cloud provider. For /vibe expressive tags ([excited], [weary], [sighs], etc) you need ElevenLabs specifically — that's the only provider that supports them today.
1. Get an API key
2. Add the keys to ~/.punt-labs/vox/keys.env
The keys file is in your home directory and owned by you — open it in your normal editor, no sudo:
nano ~/.punt-labs/vox/keys.env # or vi, code, etc
Paste any of these lines that apply. All are optional; vox auto-detects which providers are configured.
# ElevenLabs — recommended
ELEVENLABS_API_KEY=sk_...
# OpenAI
OPENAI_API_KEY=sk-proj-...
# AWS Polly via an aws CLI profile (recommended if you use the AWS CLI)
AWS_PROFILE=default
AWS_DEFAULT_REGION=us-east-1
# AWS Polly via raw credentials (alternative to a profile)
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...
# AWS_DEFAULT_REGION=us-east-1
# Optional: pin a specific provider.
# Auto-detect order: ElevenLabs > OpenAI > Polly > say (macOS) / espeak (Linux).
TTS_PROVIDER=elevenlabs
3. Restart the daemon to pick up the changes
# Linux
sudo systemctl restart voxd
# macOS
sudo launchctl kickstart -k system/com.punt-labs.voxd
This is the only sudo prompt for routine key management — systemctl and launchctl are system-level daemon managers and always require root to manage services. Editing keys.env itself is sudo-free.
4. Verify
vox doctor # report system checks and the daemon's active provider
vox unmute "hello from vox" # speak through the default provider
vox doctor reports the Python version, ffmpeg/espeak presence, daemon status, and which provider the running daemon is currently using. vox unmute should speak the phrase through your speakers within a few seconds.
If something doesn't work, the daemon log at ~/.punt-labs/vox/logs/voxd.log captures the spawn command, audio session env, exit code, elapsed time, and player stderr — enough detail to diagnose most failures without any extra tooling.
Upgrading
