Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for installing, configuring, and using the voice-elevenlabs plugin for Claude Code. The plugin integrates ElevenLabs v3 text-to-speech (TTS) capabilities, allowing Claude to provide spoken responses, generate multi-speaker dialogue, and create custom voices. It also includes automated voice notifications for a hands-free experience.
The plugin is composed of several commands for direct interaction, hooks for automated triggers, and a conversational agent that uses voice responses. The core functionality relies on an ElevenLabs API key and the claude-voice-notifications CLI tool for audio playback.
Sources: README.md:1-10, agents/voice-assistant.md:2-5
Installation and Setup
To use the plugin, you must install it within Claude Code, configure your ElevenLabs API key, and install a helper CLI for voice notifications.
Sources: README.md:12-29
Setup Flow
The following diagram illustrates the one-time setup process.
This diagram shows the four main steps for setting up the voice-elevenlabs plugin.
Sources: README.md:12-29
Setup Steps
-
Install the Plugin: Use the one-line command in Claude Code.
/plugin install adamanz/voice-elevenlabsSources: README.md:15
-
Configure API Key: Obtain a free API key from ElevenLabs and add it as an environment variable to your shell configuration file (e.g.,
~/.zshrcor~/.bashrc).echo 'export ELEVENLABS_API_KEY="your_key_here"' >> ~/.zshrc source ~/.zshrcSources: README.md:21-22
-
Install Voice Notification CLI: This package is required for playing the audio generated by the plugin.
npm install -g claude-voice-notificationsSources: README.md:25-26
-
Restart Claude Code: Restart the application to apply all changes.
Core Commands
The plugin provides several commands to interact with the ElevenLabs API.
| Command | Description | Source File |
|---|---|---|
/speak [text] | Speak text with optional emotion tags. | 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 an audio file to text. | 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:33-42
The /speak Command
The /speak command is the primary way to generate speech from text. It supports emotion tags to add nuance to the delivery.
Usage:
/speak [excited] We did it! The tests passed!
Sources: README.md:47, commands/speak.md:11
Available Emotion Tags:
| Tag | Description |
|---|---|
[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:51-60, commands/speak.md:14-22
The command can be implemented either by piping a JSON payload to claude-voice-notifications or by making a direct curl request to the ElevenLabs API.
This sequence diagram shows the flow when using the /speak command via the recommended claude-voice-notifications tool.
Sources: commands/speak.md:27-30
Voice Configuration
You can manage voice settings using the /voice-config command or by setting an environment variable.
Using /voice-config
This command allows you to view, change, and test the current voice configuration.
| Action | Description |
|---|---|
show | (Default) Displays current voice ID and API key status. |
set-voice [voice_id] | Changes the default voice. |
test | Plays a test message with the current settings. |
Sources: commands/voice-config.md:9-21
Default Voices
The plugin comes with several pre-selected voices. You can switch between them using /voice-config set-voice [voice_id] or by setting the ELEVENLABS_VOICE_ID environment variable.
| Voice | ID | Style |
|---|---|---|
| George | JBFqnCBsd6RMkjVDRZzb | Natural male (default) |
| Adam | pNInz6obpgDQGcFmaJgB | Deep male |
| Rachel | 21m00Tcm4TlvDq8ikWAM | Natural female |
| Domi | AZnzlk1XvdvUeBnXmlld | Young female |
Sources: README.md:83-90, commands/voices.md:9-16, commands/voice-config.md:15-19
To list all voices available in your ElevenLabs account, you can use the following API call:
curl -s "https://api.elevenlabs.io/v1/voices" \
-H "xi-api-key: $ELEVENLABS_API_KEY" | jq '.voices[] | {name, voice_id}'
Sources: commands/voices.md:23-25
Automated Voice Hooks
The plugin can automatically play voice notifications for certain Claude Code events, enabling a hands-free workflow. These are configured in hooks/hooks.json.
Sources: README.md:94-98, hooks/hooks.json
Hook Events
| Event | Script | Description |
|---|---|---|
Stop | stop-voice.sh | Announces "[project]: done" when Claude finishes a task. |
SubagentStop | 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
Hook Execution Flow
The following diagram shows how an event triggers a voice notification.
This diagram illustrates the process from an event in Claude Code to the final audio playback.
Sources: hooks/hooks.json, hooks/scripts/stop-voice.sh, hooks/scripts/subagent-voice.sh
The subagent-voice.sh script dynamically creates a message by extracting the project name from the current working directory and the task description from the conversation transcript.
Sources: hooks/scripts/subagent-voice.sh:6-20
Voice Assistant Agent
The voice-assistant is a conversational agent profile that formalizes the behavior of speaking responses aloud. When this agent is active, it will automatically provide a concise spoken summary after generating a text response.
Sources: agents/voice-assistant.md:2-5
Agent Behavior Flow
This flowchart shows the steps the voice-assistant agent takes to respond to a user.
Sources: agents/voice-assistant.md:9-13, skills/voice-responses.md:15-18
The agent follows specific guidelines for its spoken responses, such as keeping them brief (max 50 words) and using natural, conversational language without technical jargon.
Sources: agents/voice-assistant.md:17-19, skills/voice-responses.md:22-25