Agent Speak

CLI tool for AI agent speech notifications using ElevenLabs TTS, with a macOS say fallback.

Installation

Published usage:

npx agent-speak@latest "Hello world"

Optional global install:

npm install -g agent-speak

GitHub install also works because the package builds on install:

npm install -g github:kaizhi/agent-speak

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>

On macOS, no setup is required for the built-in say fallback.

Usage

# Speak a message
agent-speak "Task complete"

# Run without installing globally
npx agent-speak@latest "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 ElevenLabs when configured, and falls back to built-in say
• Linux: Uses mpv
• Windows: Uses PowerShell

For AI Agents

A skill is included at skills/agent-speak/SKILL.md that teaches agents to invoke the CLI via npx.