Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The voice-elevenlabs plugin integrates ElevenLabs' text-to-speech (TTS) and transcription capabilities into the Claude Code environment. Its architecture is built upon a set of user-invokable commands, event-driven hooks for automatic voice notifications, and a dependency on an external CLI tool for audio playback. This system allows users to generate speech from text, create dialogues, design custom voices, and receive audible alerts for background tasks.
The core components are the commands defined in the /commands directory, the automated hooks specified in hooks/hooks.json, and the reliance on the claude-voice-notifications npm package for handling the final audio output. Configuration is managed through environment variables for the ElevenLabs API key and preferred voice ID.
Core Components
The plugin's architecture can be broken down into three main areas: Commands, Hooks, and External Dependencies.
This diagram shows the high-level interaction between the user, the plugin's core components (Commands and Hooks), and the external systems it relies on.
Sources: README.md, hooks/hooks.json, commands/speak.md
1. Commands
Commands are user-initiated actions prefixed with / that provide direct access to the ElevenLabs API features. They are defined as individual markdown files in the commands/ directory.
| Command | Description | Source File |
|---|---|---|
/speak [text] | Speak text with optional emotion tags like [excited]. | commands/speak.md |
/dialogue | Generate multi-speaker conversations from a script. | commands/dialogue.md |
/create-voice | Create a custom voice from a text description. | commands/create-voice.md |
/transcribe | Convert an audio file (local or URL) 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:27-36
The /speak command is a primary entry point for TTS. The diagram below illustrates its execution flow.
This sequence shows how a user's /speak command is processed, ultimately resulting in audio being played back to the user.
Sources: commands/speak.md:22-26
2. Hooks
Hooks provide automated, event-driven voice notifications without direct user invocation. They are configured in hooks/hooks.json to trigger shell scripts based on events within the Claude Code environment.
The following events are configured:
| 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. |
Notification | claude-voice-notifications | Announces when Claude needs permission or input. |
Sources: hooks/hooks.json:2-17
The hook scripts are responsible for parsing context from the event payload (like the current working directory) to create a concise, relevant audio message.
This flowchart illustrates the logic within the subagent-voice.sh script.
This shows how a SubagentStop event is processed by its corresponding script to generate a dynamic voice notification.
Sources: hooks/scripts/subagent-voice.sh
3. External Dependencies & Configuration
The plugin's functionality is dependent on an external CLI tool and proper environment configuration.
claude-voice-notifications
This is a required command-line tool that acts as a bridge to the ElevenLabs API for voice notifications. It is installed globally via npm. The hook scripts and some command implementations pipe JSON-formatted messages to this tool to trigger speech.
Sources: README.md:21-23, hooks/scripts/stop-voice.sh:18, hooks/scripts/subagent-voice.sh:33
Environment Variables
Configuration is handled through shell environment variables.
| Variable | Description | Example | Source |
|---|---|---|---|
ELEVENLABS_API_KEY | Your API key for authenticating with ElevenLabs. | "your_key_here" | README.md:15-18 |
ELEVENLABS_VOICE_ID | The ID of the ElevenLabs voice to use for speech generation. | "pNInz6obpgDQGcFmaJgB" | commands/voices.md:18-22 |
The default voice is "George" (JBFqnCBsd6RMkjVDRZzb), but this can be changed by setting the ELEVENLABS_VOICE_ID variable. The /voices and /voice-config commands help manage this setting.
Sources: commands/voices.md:9-15, commands/voice-config.md:10-16
4. Voice Assistant Agent Behavior
The plugin also defines a high-level agent persona, voice-assistant. This agent's defined behavior is to provide a concise spoken summary (1-3 sentences) after generating a more detailed text response. This ensures a natural, conversational flow where complex information is written and key takeaways are spoken.
This behavior is guided by the voice-responses skill, which activates when users make voice-related requests or for accessibility purposes.
Sources: agents/voice-assistant.md:1-23, skills/voice-responses.md:1-24
Summary
The voice-elevenlabs plugin employs a straightforward yet effective architecture. It combines explicit user Commands for direct control over ElevenLabs features with automated Hooks for ambient, event-driven notifications. The system is orchestrated through shell scripts and the claude-voice-notifications CLI, with configuration managed via environment variables. This modular design allows for easy extension and provides a robust voice interface for the Claude Code environment.