Speak

When to Announce

• Planning complete - When a plan/todo list is finalized
• Issue resolved - When a bug fix or error is resolved
• Summary generated - When completing a sprint or major task

Configuration

.claude/tts-config.json

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": [],
  "voices": {
    "planning": { "provider": "google", "voice": "Kore", "style": "calm" },
    "issue": { "provider": "google", "voice": "Aoede", "style": "urgent" },
    "summary": { "provider": "google", "voice": "Charon", "style": "satisfied" }
  },
  "assigned_at": "2025-01-15T10:30:00Z"
}

references/voice-pools.json

say

Workflow

1. Detect message type - planning, issue, or summary
2. Load config - Read

   .claude/tts-config.json

   or create if missing
3. Select provider - Use first provider from

   provider_order

   not in

   unavailable_providers

4. Transform text - Convert to speech-friendly format (see below)
5. Speak - Call appropriate TTS tool with configured voice
6. Handle failures - See error handling below

Error Handling

unavailable_providers

.claude/tts-config.json

unavailable_providers

{
  "provider_order": ["google", "openai", "elevenlabs", "say"],
  "unavailable_providers": ["google"],
  ...
}

Text Transformation

/src/lib/foo.rs

• Planning: "Here's the plan..." (forward-looking, organized)
• Issue: "Found a problem..." (alert but calm)
• Summary: "All done..." (satisfied, accomplished)

TTS Tools

google_tts (preferred)

mcp__mcp-tts__google_tts
- text: string (required)
- voice: string (default: "Kore")
- model: string (default: "gemini-2.5-flash-preview-tts")

openai_tts (fallback 1)

mcp__mcp-tts__openai_tts
- text: string (required)
- voice: string (default: "alloy") - alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer, verse
- model: string (default: "gpt-4o-mini-tts")
- speed: number (0.25-4.0, default: 1.0)
- instructions: string (voice modulation hints)

elevenlabs_tts (fallback 2)

mcp__mcp-tts__elevenlabs_tts
- text: string (required)

say_tts (fallback 3 - local/free)

mcp__mcp-tts__say_tts
- text: string (required)
- voice: string (OPTIONAL - prefer leaving unset to use system default voice which sounds more natural)
- rate: integer (RECOMMENDED: 200-250 for natural speech, max 300 unless user asks faster; default: 200)

• Do NOT set a voice unless the user explicitly requests one - the system default sounds most natural
• Keep rate between 200-250 for comfortable listening; only go up to 275-300 if user wants faster speech

Auto-Assignment

1. Read

   references/voice-pools.json

   for available voices
2. Check

   ~/.claude/tts-unavailable.json

   for globally unavailable providers (shared across projects)
3. Scan

   ~/.claude/tts-assignments.json

   for voices already assigned to other projects
4. Select 3 unused voices (one per message type) from first available provider
5. If all voices used, cycle back with provider variation
6. Save assignment to both project config and global assignments file

~/.claude/tts-unavailable.json

{
  "unavailable": ["google", "elevenlabs"],
  "updated_at": "2025-01-15T10:30:00Z"
}

Examples

"Here's the plan for the authentication feature. First, I'll create the login component. Then add session management. Finally, write the tests. Three tasks total."

"Found and fixed an issue. The rate limiter wasn't catching timeout errors. Added a try-catch block in the handler. Tests are passing now."

"All done with the authentication system. Added login, logout, and session management. Created five new files and updated the main router. Ready for review."