Agent Speak

Speak messages aloud to notify the user when completing tasks.

Usage

npx --yes agent-speak "Your message here"
npx --yes agent-speak --worktree <path> "Your message here"
npx --yes agent-speak --voice <name> "Your message here"
npx --yes agent-speak --model <model-id> "Your message here"

Voice Selection

Use --worktree with the current working directory to get a deterministic voice unique to your worktree. This ensures agents in different worktrees have different voices.

npx --yes agent-speak --worktree "$(pwd)" "Task complete"

Always use the worktree flag so your voice is consistent and distinct from other agents.

Available voice presets

If you need to specify manually:

• rachel, bella, elli, freya, nicole, domi (female)
• josh, adam, sam, arnold, dave, fin, clyde (male)

npx --yes agent-speak --voice josh "Build complete"

When to Use

Speak notifications after:

• Completing a significant task
• Finishing a multi-step workflow
• Encountering an error that needs user attention
• Completing a build or deployment

Examples

# After completing a feature
npx --yes agent-speak --worktree "$(pwd)" "Finished implementing the authentication flow"

# After a build
npx --yes agent-speak --worktree "$(pwd)" "Build complete with no errors"

# After an error
npx --yes agent-speak --worktree "$(pwd)" "Build failed. Check the terminal for details"

# After a refactor
npx --yes agent-speak --worktree "$(pwd)" "Refactoring complete. Updated 12 files"

Guidelines

1. Always use npx --yes agent-speak --worktree "$(pwd)" for automatic voice selection
2. Keep messages brief (under 20 words)
3. State what happened, not technical details
4. Don't speak for trivial operations (single file edits, running commands)
5. Use natural phrasing, not robotic language

Setup

Users should configure their ElevenLabs API key for the best voices:

npx --yes agent-speak config set-key <elevenlabs-api-key>

Or set the ELEVENLABS_API_KEY environment variable.

On macOS, the CLI falls back to the built-in say command if ElevenLabs is not configured or unavailable.

To debug configuration in an agent session:

npx --yes agent-speak config show