---
slug: "agent-speak"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/kaizhi/agent-speak@main/README.md"
repo: "https://github.com/kaizhi/agent-speak"
source_file: "README.md"
branch: "main"
---
# Agent Speak

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

## Installation

Published usage:

```bash
npx agent-speak@latest "Hello world"
```

Optional global install:

```bash
npm install -g agent-speak
```

GitHub install also works because the package builds on install:

```bash
npm install -g github:kaizhi/agent-speak
```

## Setup

Set your ElevenLabs API key:

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

Or use the environment variable:

```bash
export ELEVENLABS_API_KEY=<your-api-key>
```

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

## Usage

```bash
# 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.

```bash
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   |

```bash
agent-speak --voice bella "Tests passed"
```

## Configuration

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

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

### Config Commands

```bash
# 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`.