<p align="center">
<img src="assets/logo-dark.svg#gh-dark-mode-only" width="420" alt="cc-vox">
<img src="assets/logo-light.svg#gh-light-mode-only" width="420" alt="cc-vox">
</p>
<p align="center">
<a href="https://github.com/BestSithInEU/cc-vox/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/BestSithInEU/cc-vox/tests.yml?branch=main&style=flat-square&label=tests" alt="Tests"></a>
<a href="#-quick-start"><img src="https://img.shields.io/badge/setup-2_min-brightgreen?style=flat-square" alt="Setup time"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT License"></a>
<img src="https://img.shields.io/badge/version-2.0.0-orange?style=flat-square" alt="Version">
<img src="https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
<img src="https://img.shields.io/badge/claude_code-plugin-7C3AED?style=flat-square" alt="Claude Code Plugin">
</p>
<p align="center">
Give Claude Code a voice.<br>
Hear spoken summaries after every response — zero friction, multiple TTS backends.
</p>
<br>
<details>
<summary><b>📖 Table of Contents</b></summary>
</details>
<br>
✨ Features
- 🔊 Automatic voice feedback — Claude speaks a summary after every response
- 🎯 Multi-backend TTS — Qwen3-TTS, Fish Speech, Chatterbox (GPU), Kokoro (CPU), pocket-tts (zero setup)
- 🔄 Auto-detection — Picks the best available backend automatically
- 🎛️ Slash commands — Control voice, backend, personality on the fly
- 🗣️ 9 voices — Cross-backend voice mapping between Kokoro and pocket-tts
- ⚡ Zero config fallback — pocket-tts auto-starts via
uvx, nothing to install
- 🧠 Smart GPU awareness — Skips GPU backends when your GPU is busy
- 🎭 Voice personality — Set prompts like "be chill" or "be upbeat"
🔁 How It Works
<p align="center">
<img src="assets/flow.svg" width="750" alt="cc-vox flow diagram">
</p>
[!NOTE]
The entire pipeline is hands-free. Once installed, Claude automatically includes voice summaries — no prompting required.
� Demo
┌─────────────────────────────────────────────────────────────────┐
│ $ claude │
│ │
│ You: refactor the auth module to use JWT tokens │
│ │
│ Claude: I've refactored the authentication module... │
│ [... full response ...] │
│ │
│ 📢 Done! I refactored auth to use JWT. Changed 3 files: │
│ auth.py, middleware.py, and config.py. All tests pass. │
│ │
│ 🔊 ████████████████████░░░░ Speaking... │
└─────────────────────────────────────────────────────────────────┘
The 📢 summary is extracted by the stop hook and spoken aloud through your chosen TTS backend.
🎙️ Backends
<p align="center">
<img src="assets/backends.svg" width="720" alt="TTS backends">
</p>
In auto mode (default), cc-vox tries Qwen3-TTS → Fish Speech → Chatterbox → Kokoro → pocket-tts and uses the first available.
GPU backends are skipped when GPU utilization exceeds the threshold (default 80%).
🚀 Quick Start
1. Install the plugin
claude plugin marketplace add BestSithInEU/cc-vox
claude plugin install voice
2. Pick a backend
<details>
<summary><b>Option A: Zero setup</b> — pocket-tts auto-starts via uvx, nothing to install</summary>
<br>
[!TIP]
Just use Claude Code — pocket-tts will auto-download and start on first speech. No Docker, no GPU needed.
Optionally pre-download the model:
hf download kyutai/pocket-tts
</details>
<details>
<summary><b>Option B: Kokoro</b> ⭐ recommended — great quality, CPU-only Docker</summary>
<br>