Agent Speak

CLI tool for AI agent speech notifications using ElevenLabs TTS.

Installation

npm install -g agent-speak

Or run without installing:

npx agent-speak "Hello world"

Setup

Set your ElevenLabs API key:

agent-speak config set-key <your-api-key>

Or use the environment variable:

export ELEVENLABS_API_KEY=<your-api-key>

Usage

# Speak a message
agent-speak "Task complete"

# Auto-select voice based on worktree (recommended for agents)
agent-speak --worktree "$(pwd)" "Task complete"

# Use a specific voice preset
agent-speak --voice josh "Hello world"

# Override ElevenLabs model
agent-speak --model eleven_turbo_v2_5 "Hello world"

# List available voice presets
agent-speak voices

# Show current config and where values come from
agent-speak config show

Voice Selection

Worktree-based (recommended)

Use --worktree to automatically select a consistent voice based on the working directory. Different worktrees get different voices, making it easy to distinguish between multiple agents.

agent-speak --worktree "$(pwd)" "Build finished"

Voice presets

13 preset voices are available:

| Name | Description | |------|-------------| | rachel | Calm female, American | | bella | Soft female, American | | elli | Emotional female, American | | freya | Expressive female, American | | nicole | Whisper female, American | | domi | Confident female, American | | josh | Deep male, American | | adam | Deep male, American | | sam | Raspy male, American | | arnold | Narrative male, American | | dave | Conversational male, British | | fin | Sailor male, Irish | | clyde | War veteran male, American |

agent-speak --voice bella "Tests passed"

Configuration

Config is stored in ~/.agent-speak/config.json:

{
  "apiKey": "your-api-key",
  "voiceId": "rachel"
}

Config Commands

# Set API key
agent-speak config set-key <api-key>

# Set default voice
agent-speak config set-voice <name>

# Show merged config and sources (env vs config file)
agent-speak config show

Platform Support

• macOS: Uses afplay
• Linux: Uses mpv
• Windows: Uses PowerShell

For AI Agents

A skill is included at skills/agent-speak/SKILL.md that teaches agents when and how to use this tool.