vox-dev

vox

Voice and audio for your AI coding assistant.

vox is the voice and audio layer for AI coding agents --- voice personalities, mood-aware expressive delivery, and background music, through five TTS providers with zero-config offline fallbacks. Because listening and watching the screen draw on largely separate channels, you can track your agent's progress by ear while your eyes stay on other work. It speaks when a task finishes, hits an error, or needs approval --- and it's partly entertainment, too: the agent can play DJ for you.

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.

Ways to use vox

vox is usable in three ways, all driving the same voxd audio daemon --- so it works outside a Claude Code plugin, in your own scripts or shell:

• Claude Code plugin (MCP) --- the mic MCP server gives your agent voice, /vibe, and /music tools plus notification hooks. Drive it with /vox y, /recap, /vibe, /music.
• Python library --- from punt_vox import VoxClient; async with VoxClient() as vox: await vox.synthesize("Build finished") (or the sync VoxClientSync). See Python API.
• CLI --- vox say "Build finished", vox record, vox music on. A standalone TTS tool, independent of Claude Code. See CLI.

Quick Start

curl -fsSL https://raw.githubusercontent.com/punt-labs/vox/39089a2/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/39089a2/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

vox daemon restart