claude-voice

claude-voice

Giving Claude Code a voice — adds conversational TTS narration to your Claude coding sessions using local AI models.

Claude Voice is a plugin for Claude Code that makes Claude narrate what it's doing — like having a senior engineer pair-programming with you, talking through their thought process.

All speech synthesis runs locally on your machine using the Kokoro ONNX model. No API calls, no cloud services, complete privacy.

How It Works

Claude Voice offers two modes of operation:

Stop Mode (Default)

When Claude finishes responding, a brief summary of the response is automatically spoken aloud. This provides passive, low-distraction narration.

MCP Mode

An MCP server provides a speak tool that Claude can call explicitly to narrate what it's doing. This gives Claude control over when and what to speak.

Both Mode

Both behaviors active simultaneously for maximum audio feedback.

All modes use:

• Local TTS — Kokoro ONNX model generates natural-sounding speech entirely on your machine
• Non-blocking — Audio plays in a background thread so Claude keeps working

Example Narrations

• "I'm searching through your authentication code now."
• "Found the issue. The API endpoint is missing error handling."
• "Tests are passing. Creating the pull request now."

Prerequisites

• Python 3.8+
• Claude Code CLI
• Linux: One of aplay, paplay, or ffplay for audio playback

  # Debian/Ubuntu
  sudo apt install alsa-utils
  

• macOS: No additional dependencies (uses built-in afplay)
• Windows: No additional dependencies (uses built-in winsound)

Installation

Install as a Claude Code Plugin

1. Open Claude Code and run:

   /install-plugin https://github.com/adjit/claude-voice
   

2. Run the install script to fetch the TTS model and dependencies:

   bash scripts/install.sh
   

3. (For MCP mode) Add the MCP server:

   claude mcp add claude-voice -- python /path/to/claude-voice/mcp/server.py
   

4. Restart Claude Code — narration will be active.

Local Installation (from source)

1. Clone this repository:

   git clone https://github.com/adjit/claude-voice.git
   cd claude-voice
   

2. Run the install script:

   bash scripts/install.sh
   

3. Register the plugin:

   /install-plugin file:///path/to/claude-voice
   

4. (For MCP mode) Add the MCP server:

   claude mcp add claude-voice -- python /path/to/claude-voice/mcp/server.py
   

Manual Dependency Installation

pip install -r requirements.txt
python -c "from src.model_manager import ensure_models; ensure_models()"

Configuration

Create ~/.claude-voice.json to configure the plugin:

{
  "enabled": true,
  "mode": "both",
  "voice": "af_bella",
  "speed": 1.1,
  "summary_max_length": 200
}

Mode Options

Mode	Behavior
"stop"	Speaks summary when Claude finishes responding (default)
"mcp"	Claude calls speak tool explicitly for narration
"both"	Both Stop hook and MCP server active

All Options

Setting	Type	Default	Description
enabled	bool	true	Enable/disable narration
mode	string	"stop"	Operation mode: "stop", "mcp", or "both"
voice	string	"af_bella"	Kokoro voice identifier
speed	float	1.1	Speech speed multiplier
summary_max_length	int	200	Max characters for Stop hook summaries
model_path	string	"models/kokoro-v0_19.onnx"	Path to ONNX model
voices_path	string	"models/voices.json"	Path to voice configs

Quick Toggle

Disable narration:

echo '{"enabled": false}' > ~/.claude-voice.json

Switch to MCP-only mode:

echo '{"mode": "mcp"}' > ~/.claude-voice.json

Project Structure