Claude Code Voice Hook

Make Claude Code speak its responses using local text-to-speech.

Every time Claude finishes responding, the hook automatically:

1. Extracts the response text
2. Strips markdown formatting
3. Sends it to a local TTS server
4. Plays the audio

Works with any OpenAI-compatible TTS API. Designed for Vois, but compatible with any TTS server that follows the OpenAI /v1/audio/speech format.

Requirements

• Claude Code (Anthropic's CLI)
• jq - JSON processor (brew install jq, apt install jq, or choco install jq)
• curl - HTTP client (pre-installed on macOS/Linux, available in Git Bash on Windows)
• Audio player - afplay (macOS), aplay/paplay (Linux), PowerShell (Windows)
• TTS server - Vois or any OpenAI-compatible TTS API

Windows Users

The script runs on Windows via Git Bash or WSL. Git Bash is included with Git for Windows. Audio playback uses PowerShell automatically when running in MINGW/MSYS/Cygwin environments.

Quick Install

git clone https://github.com/praneybehl/claude-code-voice-hook.git
cd claude-code-voice-hook
./install.sh

Manual Install

1. Copy the hook script:

mkdir -p ~/.claude/hooks
cp speak-response.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/speak-response.sh

2. Add to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/speak-response.sh",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

Configuration

Set environment variables to customize behavior:

Variable	Default	Description
VOIS_API_URL	http://localhost:8080/v1/audio/speech	TTS API endpoint
VOIS_API_KEY	(empty)	API key if required
VOIS_VOICE	af_heart	Voice ID to use
VOIS_ENABLED	1	Set to 0 to disable
VOIS_MAX_CHARS	1500	Max characters to speak

Example:

export VOIS_VOICE="bf_emma"
export VOIS_MAX_CHARS="2000"

Vois Voices

Vois includes 54 voices across 10 languages. Popular choices:

Voice ID	Description
af_heart	Warm, conversational American female
af_alloy	Neutral, professional American female
am_adam	Clear, authoritative American male
bf_emma	Natural British female
bm_george	Professional British male

See the full voice library in the Vois app or at vois.so/features/voices.

How It Works

Claude Code supports hooks - shell commands that run at specific lifecycle events. The Stop hook fires after Claude finishes generating a response.

The hook:

1. Reads JSON from stdin containing the transcript path
2. Parses the transcript to find the last assistant message
3. Strips markdown (code blocks become "[code block]")
4. Truncates to max characters
5. POSTs to the TTS API
6. Plays the resulting WAV file

Uninstall

./uninstall.sh

Or manually:

rm ~/.claude/hooks/speak-response.sh
# Remove the Stop hook from ~/.claude/settings.json

Troubleshooting

No audio plays

• Check that your TTS server is running
• Verify the API URL: curl http://localhost:8080/health
• Check that jq is installed: jq --version

Audio is choppy or slow

• The TTS runs after Claude responds, so long responses take time
• Reduce VOIS_MAX_CHARS for faster playback

Want to disable temporarily

export VOIS_ENABLED=0

Learn More

For a detailed guide on adding voice output to AI coding agents (Claude Code, Claude Desktop, Codex CLI, and more), check out the blog post:

Getting AI Coding Agents to Talk: Voice Output for Claude Code, Desktop & Beyond

License

MIT License - see LICENSE

Credits

Built for use with Vois - the local AI voice studio.