Voice Notification CLI
Relevant source files
The following files were used as context for generating this wiki page:
The Voice Notification CLI, claude-voice-notifications, is an external command-line tool that acts as the primary interface for this plugin to generate spoken audio via the ElevenLabs API. It is a key dependency for providing both automated, event-driven voice feedback and for handling manual speech requests from commands like /speak.
The CLI is designed to be invoked by shell scripts, receiving a JSON payload via standard input to generate specific voice messages. This architecture decouples the plugin's core logic from the direct implementation of text-to-speech synthesis.
Sources: README.md:21-23, README.md:88-89, commands/speak.md:18-20, hooks/hooks.json
Installation and Setup
To enable voice notifications, the claude-voice-notifications CLI must be installed globally using npm.
npm install -g claude-voice-notifications
This installation is a mandatory setup step for the voice-elevenlabs plugin to function correctly. The CLI relies on the ELEVENLABS_API_KEY environment variable being set to authenticate with the ElevenLabs API.
Sources: README.md:21-23, README.md:15-18
Architecture and Data Flow
The CLI is triggered by Claude Code events or direct command invocations. The general flow involves a Claude event triggering a hook, which executes a shell script. This script then pipes a JSON object to the claude-voice-notifications command, which handles the TTS conversion.
The following diagram illustrates the high-level data flow for automated notifications.
This diagram shows how an event in Claude Code triggers a hook script, which then uses the claude-voice-notifications CLI to generate audio.
Sources: hooks/hooks.json, hooks/scripts/stop-voice.sh, hooks/scripts/subagent-voice.sh, commands/speak.md:18-20
Automated Hooks
The plugin uses Claude Code's hook system to provide automatic voice notifications for key events. These are defined in hooks/hooks.json and trigger specific shell scripts that use the claude-voice-notifications CLI.
| Event | Command / Script | Description |
|---|---|---|
Stop | ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop-voice.sh | Announces "[project]: done" when Claude finishes a task. |
SubagentStop | ${CLAUDE_PLUGIN_ROOT}/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:2-17
stop-voice.sh Script
This script triggers on the Stop event. Its purpose is to provide a simple, context-aware notification that a task has finished.
- It reads the event payload from
stdin. - It extracts the current working directory (
cwd). - It derives a
projectname from the base name of thecwd. - It constructs a message:
"[project]: done"if a project name is found, otherwise"Claude done". - It pipes a JSON object containing this message to
claude-voice-notifications.
Sources: hooks/scripts/stop-voice.sh
subagent-voice.sh Script
This script, triggered by SubagentStop, provides a more detailed notification about the completed sub-task.
The logic for message construction is as follows:
This flowchart details the logic within subagent-voice.sh for creating a context-specific voice notification.
Sources: hooks/scripts/subagent-voice.sh
Manual Invocation
The claude-voice-notifications CLI is also used for direct, user-initiated speech via the /speak command.
/speak Command
The /speak command's implementation directly invokes the CLI by piping a JSON payload to it. This allows users to convert any text, including emotion tags, into speech.
The core command is:
echo '{"hook_event_name": "Stop", "message": "TEXT_HERE"}' | claude-voice-notifications
Sources: commands/speak.md:18-20
The following sequence diagram shows the interaction when a user runs the /speak command.
This diagram shows the sequence from a user typing /speak to the audio being played back.
Sources: commands/speak.md:1-20, README.md:36-42