Claude Speaker

A Claude Code plugin that automatically reads plans aloud using ElevenLabs text-to-speech when Claude enters plan mode.

Features

• 🎙️ Automatically detects when Claude creates a plan and reads it aloud
• 🗣️ Natural speech formatting - plans sound conversational, not robotic
• 🎚️ Configurable voices and speech settings via ElevenLabs
• 🔇 Easy enable/disable with slash commands
• ⚡ Simple setup process

Installation

Global Installation (Recommended)

npm install -g claude-speaker

Local Installation

npm install claude-speaker

Quick Setup

npx claude-speaker setup

Setup

1. Get an ElevenLabs API Key

   • Sign up at ElevenLabs
   • Go to your profile settings
   • Copy your API key

2. Run Setup

   claude-speaker setup
   # or if installed locally
   npx claude-speaker setup

   This will:

   • Ask for your ElevenLabs API key
   • Let you choose from available voices
   • Configure voice settings
   • Show you how to integrate with Claude Code

3. Configure Claude Code Hooks

   To configure the hooks, add the following to your Claude Code settings JSON file. This file is typically located in your Claude Code configuration directory, often found at ~/.claude/settings.json or a similar path depending on your setup:

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "/path/to/claude-speaker/src/hooks/plan-detector.js"
             }
           ]
         }
       ]
     }
   }

4. Create Enable/Disable Commands (Optional)

   Create ~/.claude/commands/speaker-enable.md:

   Enable Claude Speaker
   
   !npx claude-speaker enable

   Create ~/.claude/commands/speaker-disable.md:

   Disable Claude Speaker
   
   !npx claude-speaker disable

Usage

Once configured, Claude Speaker will automatically:

1. Detect when Claude generates a plan (when you see "Here is Claude's plan:")
2. Reformat the plan for natural speech
3. Send it to ElevenLabs for text-to-speech
4. Play the audio

Commands

• /speaker-enable - Enable Claude Speaker (if you created the command)
• /speaker-disable - Disable Claude Speaker (if you created the command)
• npx claude-speaker enable - Enable from terminal
• npx claude-speaker disable - Disable from terminal
• npx claude-speaker setup - Reconfigure settings

Configuration

Configuration is stored in ~/.claude-speaker/config.json:

{
  "enabled": true,
  "elevenLabsApiKey": "your-api-key",
  "voiceId": "selected-voice-id",
  "voiceName": "Selected Voice",
  "modelId": "eleven_multilingual_v2",
  "voiceSettings": {
    "stability": 0.75,
    "similarityBoost": 0.75,
    "style": 0.5,
    "useSpeakerBoost": true
  }
}

How It Works

1. Plan Detection: A hook monitors Claude's output for plan generation
2. Natural Formatting: Plans are reformatted to sound conversational:
   • Technical terms → Natural speech
   • Bullet points → Flowing sentences
   • Code references → Readable descriptions
3. Text-to-Speech: ElevenLabs converts the formatted text to audio
4. Playback: Audio is played automatically and cleaned up

Troubleshooting

• No audio? Check if Claude Speaker is enabled: npx claude-speaker enable
• API errors? Verify your ElevenLabs API key: npx claude-speaker setup
• Hook not working? Ensure the hook path in Claude Code settings is absolute
• Installation issues? Try installing globally with npm install -g claude-speaker

Uninstallation

Remove the npm package

For global installation:

npm uninstall -g claude-speaker

For local installation:

npm uninstall claude-speaker

Clean up configuration

1. Remove the configuration directory:

   rm -rf ~/.claude-speaker

2. Remove the hook from your Claude Code settings JSON file (typically ~/.claude/settings.json)

3. Remove the command files (if you created them):

   rm ~/.claude/commands/speaker-enable.md
   rm ~/.claude/commands/speaker-disable.md

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for Claude Code by Anthropic
• Powered by ElevenLabs text-to-speech API