🎤 Voice Code

Claude Code, out loud. Stop reading the chat — let Claude speak its responses in real-time with natural-sounding neural voices.

Voice Code hooks into Claude Code's streaming output, strips code blocks and markdown, and speaks the text aloud using Gemini TTS, Azure Speech, or Kokoro (local, free, no API key). Hands-free coding, finally.

✨ Features

• Real-time streaming — audio starts before Claude finishes typing
• Smart text cleaning — code blocks skipped, inline code kept, URLs and acronyms handled naturally
• 30+ neural voices — Gemini voices (Kore, Puck, Fenrir...), Azure voices (Jenny, Guy, Aria...), and 28 Kokoro voices
• Three TTS providers — Google Gemini, Microsoft Azure Speech, or Kokoro (local ONNX model, free, offline)
• Cross-platform — Linux (ALSA/PulseAudio), macOS (afplay), Windows (PowerShell)
• Zero config — voice-code setup walks you through everything

🚀 Install

npm install -g @vegetz/voice-code

Why npm, not pnpm? If you want the Kokoro (local) provider, install with npm. kokoro-js depends on @huggingface/transformers, which imports onnxruntime-common without declaring it as a dependency — pnpm's strict node_modules can't resolve that undeclared import and voice-code setup crashes when Kokoro loads. npm's flat node_modules doesn't have this restriction. If you only use Gemini or Azure and never touch Kokoro, pnpm install -g @vegetz/voice-code works fine too.

Or install from git:

npm install -g https://github.com/VeGETz/VoiceCode.git

Or clone and install locally:

git clone https://github.com/VeGETz/VoiceCode.git
cd VoiceCode
npm install -g .

Requires Node.js 18+.

⚡ Quick Start

voice-code setup

The wizard will:

1. Ask you to pick a TTS provider (Gemini or Azure)
2. Guide you through API key setup
3. Let you browse and preview voices
4. Verify audio playback works
5. Auto-configure the Claude Code hook

That's it. Claude will start speaking.

🎮 Commands

Command	Description
voice-code setup	Guided setup wizard
voice-code on	Enable TTS
voice-code off	Disable TTS
voice-code toggle	Toggle TTS on/off
voice-code shutup	Stop all audio immediately (clears queue, kills worker)
voice-code test [text]	Test TTS with sample text
voice-code voices	List available voices
voice-code uninstall	Remove hook and config, then uninstall package
voice-code log [n]	Show last n log entries

🔑 API Keys

Gemini (Google)

Get a free API key at aistudio.google.com/apikey

Set via environment variable:

export GEMINI_API_KEY=your-key-here

Or let the setup wizard save it to ~/.voice-code/config.json.

Azure Speech (Microsoft)

Create a Speech resource in the Azure Portal.

Set via environment variables:

export AZURE_SPEECH_KEY=your-key-here
export AZURE_SPEECH_REGION=eastus

Or enter them during voice-code setup.

Kokoro (Local, free)

No API key, no account, no cost — runs entirely on your machine via ONNX.

First use downloads the ~80MB model (onnx-community/Kokoro-82M-v1.0-ONNX), cached afterward. Pick it during voice-code setup.

🎙️ Voices

Gemini Voices

30 voices with distinct personalities — bright, firm, excitable, warm, casual...

voice-code voices

Azure Voices

Hundreds of neural voices across 100+ languages. Fetched live from the Azure API during setup.

voice-code voices

Kokoro Voices

28 local voices (US/GB, male/female), default af_heart (warm, natural).

voice-code voices

⚙️ Configuration

Config lives at ~/.voice-code/config.json:

{
  "provider": "gemini",
  "voice": "Kore",
  "model": "gemini-3.1-flash-tts-preview",
  "enabled": true,
  "playbackDevice": null,
  "azureKey": null,
  "azureRegion": null,
  "azureVoice": "en-US-JennyNeural",
  "kokoroVoice": "af_heart",
  "kokoroDtype": "q8"
}

Field	Description
provider	"gemini", "azure", or "kokoro"
voice	Gemini voice name
model	Gemini TTS model (default gemini-3.1-flash-tts-preview)
apiKeyEnv	Env var name to read the Gemini key from (default GEMINI_API_KEY)
azureVoice	Azure voice name (e.g., en-US-JennyNeural)
azureRegion	Azure region (e.g., eastus, westeurope)
azureKey	Azure Speech resource key
kokoroVoice	Kokoro voice name (default af_heart)
kokoroDtype	Kokoro model quantization: fp32, fp16, q8, q4, q4f16 (default q8)
playbackDevice	Audio device override (null = auto-detect)

Logs are written to ~/.voice-code/voice-code.log — view with voice-code log [n].

🔧 How It Works

Claude Code (MessageDisplay hook)
  → tts-bridge.js (per response chunk, via stdin)
    → clean markdown, split into sentence-sized chunks
    → append complete chunks to a shared queue file
    → spawn tts-worker.js (detached) if none is already running
        tts-worker.js
          → reads the queue, synthesizes via Gemini, Azure, or Kokoro
          → pre-fetches the next sentence while the current one plays
          → re-checks the queue after each pass for late arrivals
          → releases its lock file and exits when the queue is empty

1. Claude Code's MessageDisplay hook streams each response chunk to tts-bridge.js via stdin
2. Text is buffered and cleaned continuously; complete sentence-sized chunks (~300 chars, split on ., !, ?) are appended to a shared queue file in the OS temp dir
3. Code blocks are stripped entirely; inline code keeps content but drops backticks
4. URLs become "link", acronyms are spelled out, symbols are expanded
5. tts-bridge.js spawns a detached tts-worker.js process guarded by a lock file — if a worker is already running, new chunks just get queued for it
6. tts-worker.js synthesizes sentences via the configured provider (Gemini, Azure, or Kokoro) and plays them in order, pre-fetching the next sentence's audio while the current one plays so synthesis latency is hidden behind playback
7. This all happens out-of-process from the hook, so Claude Code is never blocked waiting on audio

🖥️ Cross-Platform Audio

Platform	Backend	Notes
Linux	paplay / aplay	PulseAudio or ALSA
macOS	afplay	Built-in
Windows	PowerShell SoundPlayer	Built-in

Detected automatically. No extra install needed.

🤝 Contributing

git clone https://github.com/VeGETz/VoiceCode.git
cd VoiceCode
pnpm install
node scripts/tts-bridge.js   # test the bridge

⚠️ Disclaimer

This project was 100% created by AI. Use at your own risk.

Using this software with Gemini TTS or Azure Speech will incur costs on your respective cloud accounts. The author takes no responsibility for any charges, damages, or issues arising from the use of this software.

📄 License

MIT