kokoro-tts

# Kokoro TTS Plugin for Claude Code

Text-to-speech for Claude Code responses using [Kokoro](https://github.com/thewh1teagle/kokoro-onnx), a fast local neural TTS engine.

## Features

- **Auto-read responses**: Claude's responses are automatically read aloud
- **Per-session voices**: Each Claude session gets its own unique voice
- **Queue system**: Multiple responses queue up and play in order (no overlapping)
- **Smart markdown handling**: Code blocks are summarized, formatting is stripped
- **Fully local**: No API calls, runs entirely on your machine

## Installation

### 1. Install the plugin

```bash
/plugin marketplace add voiys/kokoro-tts-plugin
/plugin install kokoro-tts@voiys-kokoro-tts-plugin
```

### 2. Run setup

The first time you use the plugin, run the setup script to download models (~340MB):

```bash
~/.claude/plugins/cache/kokoro-tts/kokoro-tts-plugin/scripts/setup.sh
```

Or after installation, the plugin will prompt you to run setup.

## Requirements

- macOS (Apple Silicon or Intel)
- Python 3.10 or higher
- ~400MB disk space for models

## Stop Hotkey (Optional)

Set up a global hotkey to stop TTS at any time:

1. Install skhd:
   ```bash
   brew install koekeishiya/formulae/skhd
   ```

2. Add to `~/.skhdrc`:
   ```
   ctrl + shift - s : ~/.kokoro-tts/stop.sh
   ```

3. Grant accessibility permissions to skhd (System Settings → Privacy & Security → Accessibility)

4. Start skhd:
   ```bash
   skhd --start-service
   ```

Now press **Ctrl+Shift+S** to stop TTS at any time.

## Available Voices

The plugin automatically assigns one of these voices to each session:

| Voice | Gender | Accent |
|-------|--------|--------|
| Heart | Female | American |
| Adam | Male | American |
| Bella | Female | American |
| Michael | Male | American |
| Nova | Female | American |
| Eric | Male | American |
| Sky | Female | American |
| Liam | Male | American |
| Emma | Female | British |
| George | Male | British |
| Sarah | Female | American |
| Onyx | Male | American |

## How It Works

1. A `Stop` hook triggers after each Claude response
2. The response text is extracted and queued
3. Markdown is converted to speakable text
4. Kokoro synthesizes speech locally
5. Audio plays through your default output device

## Data Storage

All data is stored in `~/.kokoro-tts/`:
- `models/` - Kokoro ONNX model and voice files
- `venv/` - Python virtual environment
- `tts-queue.json` - Message queue
- `stop.sh` - Stop script for hotkey

## Troubleshooting

**No audio playing:**
- Check that setup completed successfully
- Verify your audio output device is working
- Check `~/.kokoro-tts/` exists with models

**Python errors:**
- Ensure Python 3.10+ is installed: `brew install [email protected]`
- Re-run setup script

**Stop hotkey not working:**
- Verify skhd has accessibility permissions
- Check skhd is running: `pgrep skhd`
- Restart skhd: `skhd --restart-service`

## License

MIT