vox-dev

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.

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

uv tool install punt-vox
vox install
vox doctor

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