claude-speak
Voice output layer for Claude Code. Converts Claude's text responses into natural speech and plays them through your local speakers, so you can work hands-free.
This is not a voice input system and it is not the built-in Claude Code voice mode. It is a dedicated text-to-speech plugin that gives Claude the ability to speak its responses aloud, either automatically at the end of every turn or deliberately when something warrants your audible attention.
Table of Contents
Features
- Passive voice -- Automatically speaks Claude's final message at the end of each turn via hooks
- Active voice -- Claude can choose to speak mid-turn when something warrants your immediate audible attention (build failures, blocking questions, completed milestones)
- Session mute/unmute -- Mute and unmute voice output within a session without editing config files; every new session starts fresh
- Multi-provider TTS -- Supports both OpenAI (
gpt-4o-mini-tts) and ElevenLabs, with full configuration for each provider stored side by side
- Subcommand system -- Control provider, voice, speed, mute, and more via
/speak: subcommands without leaving your session
- Smart deduplication -- A lockfile-based cooldown prevents passive and active voice from double-speaking the same content
- Markdown sanitization -- Strips headers, bold/italic, code fences, tables, links, and HTML before sending text to TTS, so speech sounds natural
- Table-to-speech conversion -- Markdown tables are converted to "Header: Value" pairs for intelligible spoken output
- Voice cache -- ElevenLabs voices are cached locally for fast name-to-ID resolution without repeated API calls
- Auto-migration -- Upgrades from the old flat config format to the new nested format automatically
Prerequisites
Before installing claude-speak, make sure you have the following:
1. Claude Code CLI
You need Claude Code installed and working. claude-speak is a Claude Code plugin and cannot run standalone.
# Install Claude Code if you haven't already
npm install -g @anthropic-ai/claude-code
2. Node.js 18+
The plugin requires Node.js 18 or later (20+ recommended). Check your version:
node --version
3. TTS API Key
claude-speak supports two TTS providers. You need at least one API key:
4. Audio Playback
Your system needs a command-line audio player:
| Platform | Required Player | Notes |
|---|
| macOS | afplay | Built-in, nothing to install |
| Linux | paplay or aplay | Install via pulseaudio-utils or alsa-utils |
The plugin auto-detects the correct player for your platform.
Installation
Install from the Claude Code plugin marketplace:
claude plugin install claude-speak
During installation, you will be prompted for your OpenAI API key. This key is stored securely in your system keychain via the Claude Code plugin system.
Post-Installation Setup
After installation, two additional steps are required before voice output will work.
Step 1: Create the Configuration File
Copy the example configuration to your home directory:
cp "$(cat ~/.claude-speak/plugin-root)/claude-speak.example.json" ~/.claude-speak.json
Then edit ~/.claude-speak.json to customize your preferences. See the Configuration Reference below for all options.
Step 2: Configure API Keys
API keys are configured during plugin installation. Claude Code prompts you for your OpenAI and/or ElevenLabs API keys and stores them securely in your system keychain. Keys are never written to disk or exposed in conversation context.
If you need to reconfigure your keys, reinstall the plugin:
claude plugin install claude-speak
Alternative: If you prefer, you can set OPENAI_API_KEY and/or ELEVENLABS_API_KEY in your shell profile (.zshrc, .bashrc, etc.) instead of using the keychain. The plugin checks both sources.
Step 3: Restart Claude Code
pchalasani
TwinPeaksTownie
husniadil
Cleanser-Labs
jeremylongshore
mbailey