Home
Relevant source files
The following files were used as context for generating this wiki page:
The voice-elevenlabs plugin integrates ElevenLabs' v3 text-to-speech (TTS) and transcription capabilities directly into the Claude Code environment. It allows users to add natural and expressive voice output to their interactions with Claude, create custom voices, generate multi-speaker dialogues, and transcribe audio files. The plugin is designed to enhance accessibility and provide a more conversational, hands-free user experience.
This system is composed of a set of user-invokable commands for direct voice control and automated hooks that provide voice notifications for key events within the Claude Code workflow. It also includes a pre-configured conversational agent (voice-assistant) that leverages these tools to provide spoken responses automatically.
Sources: README.md:1-10, agents/voice-assistant.md:3-7
Installation and Setup
To use the plugin, it must be installed in Claude Code, and an ElevenLabs API key must be configured. An additional CLI tool is required for voice notifications.
Sources: README.md:12-29
Setup Flow
The following diagram illustrates the one-time setup process.
Sources: README.md:12-29
Step-by-step Instructions
- Install the Plugin: Use the built-in Claude Code command.
/plugin install adamanz/voice-elevenlabs - Configure API Key: Obtain a free API key from ElevenLabs and add it as an environment variable.
echo 'export ELEVENLABS_API_KEY="your_key_here"' >> ~/.zshrc source ~/.zshrc - Install Notification CLI: This global NPM package is used by the plugin's hooks to play audio.
npm install -g claude-voice-notifications - Restart Claude Code: To ensure all changes are loaded.
Sources: README.md:15-27
Core Commands
The plugin provides several commands to interact with the ElevenLabs API for TTS, voice design, and transcription.
| Command | Description | Source File |
|---|---|---|
/speak [text] | Speak text with emotion tags [excited], [whispers], etc. | commands/speak.md |
/dialogue | Generate multi-speaker conversations. | commands/dialogue.md |
/create-voice | Create a custom voice from a text description. | commands/create-voice.md |
/transcribe | Convert audio to text (Scribe v2). | commands/transcribe.md |
/voices | List available ElevenLabs voices. | commands/voices.md |
/voice-config | View and modify voice settings. | commands/voice-config.md |
Sources: README.md:31-44
/speak
This command converts text to speech using the configured ElevenLabs voice. It supports v3 Audio Tags for adding emotional nuance.
Available Emotion Tags:
| Tag | Emotion |
|---|---|
[excited] | Enthusiastic |
[whispers] | Quiet, intimate |
[laughs] / [laughing] | Natural laughter |
[sighs] | Thoughtful pause |
[angry] | Intense |
[sad] | Melancholic |
[nervous] | Hesitant |
[shouting] | Loud |
[sarcastically] | Dry humor |
Sources: README.md:48-62, commands/speak.md:11-20
Example:
/speak [excited] We did it! The tests passed!
Sources: README.md:50
The diagram below shows the data flow when the /speak command is executed.
This diagram illustrates the process of converting text to speech and playing it, as detailed in the command's implementation guide. Sources: commands/speak.md:27-33
/dialogue
Generates a conversation between multiple speakers, preserving natural timing and allowing for interruptions. Different voices can be assigned to each speaker.
Example:
/dialogue "Alice: Hey, did you see the new feature?
Bob: [excited] Yes! It's incredible!
Alice: [laughs] I knew you'd love it."
Sources: README.md:66-69, commands/dialogue.md:10-14
/create-voice
Uses ElevenLabs Voice Design v3 to generate a new, unique AI voice from a text description. The command prompts ElevenLabs to generate options, which can then be saved to the user's account.
Example:
/create-voice "warm female narrator, mid-30s, slight British accent, professional"
Sources: README.md:73-75, commands/create-voice.md:20-22
/transcribe
Converts an audio file (local or from a URL) into text using ElevenLabs Scribe v2. The output can include speaker labels and timestamps.
Example:
/transcribe file:~/meeting.mp3
Sources: README.md:79-81, commands/transcribe.md:26-28
Voice Management
The /voices and /voice-config commands are used to manage voice settings.
/voices: Lists available pre-made and custom voices./voice-config: Allows viewing the current configuration, changing the default voice ID, and testing the setup.
The default voice is determined by the ELEVENLABS_VOICE_ID environment variable.
Default Voices:
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
Sources: README.md:85-93, commands/voices.md:8-15, commands/voice-config.md:8-16
Automated Voice Hooks
The plugin uses hooks to automatically trigger voice notifications for specific events in Claude Code, providing ambient, hands-free updates.
Sources: README.md:95-101, hooks/hooks.json:2-18
This diagram shows how events trigger the voice notification scripts.
Hook Definitions:
| Event | Script/Command | Description |
|---|---|---|
Stop | hooks/scripts/stop-voice.sh | Announces "[project]: done" when Claude finishes a task. |
SubagentStop | hooks/scripts/subagent-voice.sh | Announces "[project]: [task]" when a subagent completes its task. |
Notification | claude-voice-notifications | Announces when Claude needs permission or user input. |
Sources: hooks/hooks.json:3-17
The shell scripts (stop-voice.sh and subagent-voice.sh) parse the current working directory to determine the project name and, in the case of a subagent, the task description from the transcript to create a concise, context-aware audio message.
Sources: hooks/scripts/stop-voice.sh:5-15, hooks/scripts/subagent-voice.sh:5-30
Agents and Skills
The plugin includes a voice-assistant agent and a voice-responses skill to integrate voice capabilities into conversational flows.
Sources: agents/voice-assistant.md, skills/voice-responses.md
voice-assistant Agent
A conversational agent pre-configured to use the ElevenLabs tools. Its behavior is to generate a text response and then speak a concise (1-3 sentence) summary of that response. This provides a dual-modality experience where detailed information is in text and a high-level summary is spoken.
Sources: agents/voice-assistant.md:3-12
voice-responses Skill
This skill defines the logic for when and how Claude should speak responses aloud. It activates when a user explicitly asks for a spoken response (e.g., "read this to me") or mentions hands-free/accessibility needs. The guidelines state that spoken summaries should be brief (max 50 words) and use conversational language.
Sources: skills/voice-responses.md:3-25
Summary
The voice-elevenlabs plugin provides a comprehensive suite of tools for integrating high-quality voice interaction into Claude Code. Through a combination of direct commands and automated hooks, it enables text-to-speech with emotional nuance, multi-speaker dialogue generation, voice creation, and audio transcription. This enhances the user experience by making interactions more natural, accessible, and efficient.
Sources: README.md:8-10, demo-script.md