Installation

This document provides a comprehensive guide to installing and configuring the voice-elevenlabs plugin for Claude Code. This plugin integrates the ElevenLabs v3 API to provide natural text-to-speech (TTS), voice creation, and audio transcription capabilities directly within the Claude Code environment. Proper installation involves setting up the plugin, configuring API keys, and installing a necessary command-line utility for voice notifications.

Sources: README.md:5-6

Prerequisites

Before installing the plugin, ensure you have the following components. These are required for the plugin to function correctly.

Installation and Setup Flow

The following diagram illustrates the complete installation and configuration process from start to finish.

This diagram shows the required steps for a successful installation. Sources: README.md:9-33

Detailed Installation Steps

Step 1: Install the Plugin

There are two methods to install the voice-elevenlabs plugin in Claude Code.

Method 1: One-Command Install (Recommended)

The simplest way to install the plugin is by using the built-in /plugin command within Claude Code.

/plugin install adamanz/voice-elevenlabs

Sources: README.md:11-13

Method 2: Manual Installation

Alternatively, you can clone the repository directly into your Claude plugins directory.

cd ~/.claude/plugins
git clone https://github.com/adamanz/voice-elevenlabs.git

Sources: README.md:15-18

Step 2: Configure ElevenLabs API Key

The plugin requires an ElevenLabs API key to function.

1. Obtain a free API key from the ElevenLabs website.
2. Add the key to your shell's configuration file (e.g., ~/.zshrc or ~/.bashrc) as an environment variable.

echo 'export ELEVENLABS_API_KEY="your_key_here"' >> ~/.zshrc
source ~/.zshrc

This ensures the API key is available in your environment for the plugin to use. The plugin can verify the key's presence via the /voice-config command.

Sources: README.md:22-26, commands/voice-config.md:13

Step 3: Install Voice Notification CLI

For voice notifications on events (e.g., when a task is complete), a separate CLI tool must be installed globally via NPM. This tool is triggered by the plugin's hooks.

npm install -g claude-voice-notifications

The hooks.json file defines events like Stop and SubagentStop that execute shell scripts, which in turn pipe messages to this claude-voice-notifications command.

Sources: README.md:29-31, hooks/hooks.json:3-15, hooks/scripts/subagent-voice.sh:33

Step 4: Restart Claude Code

After completing the previous steps, you must restart your Claude Code application for all changes, particularly the environment variables, to take effect.

Sources: README.md:33

Environment Configuration

The plugin's behavior is controlled by environment variables.

You can change the active voice by setting the ELEVENLABS_VOICE_ID. A list of available voices and their IDs can be retrieved using the /voices command.

Sources: README.md:25, 82-83, commands/voices.md:19-21

Verifying the Installation

Once installation is complete, you can verify that everything is working correctly.

1. Check Configuration: Run the /voice-config command to see the current voice ID and API key status.
2. Test Speech: Use the test action to hear a sample message.

   /voice-config test
   

3. Basic TTS: Use the /speak command to convert text to speech.

   /speak Hello world!
   

The following sequence diagram shows the interaction between the user, the plugin, and external services during a /speak command.

This diagram illustrates how a user command is processed through the plugin and its dependencies to produce speech. Sources: commands/voice-config.md:11, 21, commands/speak.md:11, 21-23