claude-kokoro-tts

Claude Kokoro TTS Plugin

Text-to-speech integration for Claude Code using Kokoro-FastAPI with voice blending, streaming, and comprehensive format support.

What This Plugin Installs

Plugin Files (in Claude Code's plugin cache)

Directory	Contents	Purpose
.claude-plugin/	plugin.json	Plugin manifest
commands/	8 markdown files	Slash command definitions
hooks/	hooks.json	Automatic TTS notifications on events
scripts/	4 scripts	Python wrapper + notification scripts
python/	claude_tts.py + modules/	TTS Python code (~7,500 lines)
skills/	SKILL.md	TTS notification skill

Note: Plugin files are copied to Claude Code's plugin cache directory when installed. The original plugin directory is not modified.

Files Created on Your System

Location	Purpose	Size
~/.claude_tts/cache/	Audio cache (speeds up repeated phrases)	Up to 1GB
~/.claude_tts/config.yml	User configuration file (optional)	<1KB
~/.claude_tts/preload.json	Custom preload messages (optional)	<1KB

These directories are created automatically on first use and persist across plugin updates.

Configuration File (NEW in v1.2.0)

Create a .claude_tts.yml file in your project root or ~/.claude_tts/config.yml to customize defaults:

# Server configuration
server:
  url: http://localhost:8880

# Audio settings
audio:
  voice: af_bella      # af_bella, af_sky, am_adam, bf_emma, etc.
  format: wav          # wav, mp3, pcm, opus, flac
  speed: 1.0           # 0.5 to 2.0

# Mode flags
notification: false    # Optimized for Claude Code hooks
quiet: false           # Suppress output
preload: true          # Preload messages at startup

Precedence: CLI args > project .claude_tts.yml > user ~/.claude_tts/config.yml > hardcoded defaults

Network Connections

Destination	Purpose	When
localhost:8880	Kokoro-FastAPI server	Every TTS request

No external network calls - all TTS processing happens locally via your Docker container.

System Dependencies (User Must Install)

Dependency	Install Command	Purpose
uv	curl -LsSf https://astral.sh/uv/install.sh | sh	Python package manager
Docker	docker.com	Runs Kokoro server
portaudio (optional)	brew install portaudio	Streaming audio

Python Packages (Auto-Installed by uv)

These are installed automatically to an isolated environment when you first run a command:

• requests>=2.31.0 - HTTP client for API calls
• pygame>=2.5.0 - Audio playback
• click>=8.1.0 - CLI framework
• python-dotenv>=1.0.0 - Environment config
• pydantic>=2.0.0 - Data validation
• pyaudio>=0.2.11 - Streaming audio (optional)
• pyyaml>=6.0 - YAML config (optional)

Prerequisites

1. Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# macOS (Homebrew)
brew install uv

2. Start Kokoro Server

docker run -d --restart unless-stopped --name kokoro -p 8880:8880 \
  ghcr.io/remsky/kokoro-fastapi-cpu:latest

Verify it's running:

curl http://localhost:8880/health

Installation

Method 1: Development/Testing (Temporary)

Load the plugin directly for the current session:

claude --plugin-dir /path/to/claude-kokoro-tts

This loads the plugin without installation - useful for testing.

Method 2: Interactive Installation (Recommended)

Use the /plugin command within Claude Code:

/plugin

Then browse, install, and enable the plugin interactively.

Method 3: Manual Settings (Advanced)

Add to your .claude/settings.json:

{
  "enabledPlugins": {
    "claude-kokoro-tts": true
  }
}

Note: The enabledPlugins setting is always manual - it is not automatically set during installation. This method requires the plugin files to already be in Claude Code's plugin cache.

Usage

Slash Commands

Command	Example
Speak text	/claude-kokoro-tts:speak Hello world!
Voice blend	/claude-kokoro-tts:speak --voice af_bella+af_sky "Blended"
List voices	/claude-kokoro-tts:voices
Test setup	/claude-kokoro-tts:test
Export audio	/claude-kokoro-tts:export speech.mp3 "Save this"
Interactive mode	/claude-kokoro-tts:interactive
Phoneme analysis	/claude-kokoro-tts:phonemes "Hello"
Server stats	/claude-kokoro-tts:stats
Cache stats	/claude-kokoro-tts:cache stats
Clear cache	/claude-kokoro-tts:cache clear all

Voice Blending

Combine voices with + syntax:

• af_bella+af_sky - Equal mix
• af_bella(2)+af_sky(1) - 2:1 weighted ratio

Quick Notifications

For fast, non-blocking speech:

/claude-kokoro-tts:speak -n -b -q "Build complete"