claude-speak 0.1.0

Hear every Claude Code reply without lifting a finger. Installs as a Claude Code hook — no API keys, no config required.

Claude picks up a tool  →  "Reading the config…"  spoken aloud
Claude picks up a tool  →  "Running the tests…"   spoken aloud
Claude finishes         →  full reply              spoken aloud

Recommended mode: narrate — voices each tool call as Claude works, then speaks the final reply. You always know what Claude is doing without looking at the screen.

Default backend: Microsoft Edge TTS (free, neural, online). Swap to system for fully offline playback (Windows SAPI / macOS say / Linux espeak-ng).

---

Install

# 1. Install the package
pipx install claude-speak

# 2. Register hooks in ~/.claude/settings.json
claude-speak install-interview   # recommended: narrate tool calls + speak final reply
# claude-speak install           # minimal: speak final reply only

Python ≥ 3.9 required. pipx keeps it isolated — pip install claude-speak also works.

Platform notes

Platform	Notes
Windows	Works out of the box. Edge TTS recommended (better quality than SAPI).
macOS	Works out of the box. Uses say in system mode.
Linux	Install espeak-ng for system mode: sudo apt install espeak-ng. Edge TTS works on all distros.

---

How it works

Two hooks wire into Claude Code's event system:

• PreToolUse — fires before each tool call, speaks a short description of what Claude is about to do ("Searching for config files…", "Running tests…")
• Stop — fires at the end of every turn, speaks the full final reply after stripping code blocks and markdown

Three speaking modes control what gets spoken:

Mode	What's spoken	How to enable
narrate ✦ recommended	Tool calls narrated live, then the final reply	claude-speak install-interview
end	The full final response only	claude-speak install
end + speaker-only	Only the 🔊 Speaker: line if present	claude-speak install-speaker

---

Slash commands

Type these directly in the Claude Code prompt:

Command	What it does
/claude-speak:shh	Stop speaking immediately
/claude-speak:mode	Toggle between end and narrate
/claude-speak:speaker-only	Speak only the 🔊 Speaker: summary line
/claude-speak:speaker-full	Speak the full response (default)
/claude-speak:narrate	Enable narrate mode (speaks while working)
/claude-speak:narrate-stop	Disable narrate mode
/claude-speak:config	Show current configuration
/claude-speak:help	Show help text
/claude-speak:uninstall	Remove all hooks and slash commands

---

CLI reference

claude-speak install            # register Stop hook
claude-speak install-speaker    # register Speaker-line extraction
claude-speak install-interview  # register narrate (PreToolUse) hook
claude-speak uninstall          # remove all hooks
claude-speak uninstall-interview

claude-speak speak "hello"      # one-shot TTS test
claude-speak voices             # list available voices
claude-speak config show        # show all settings
claude-speak config set <key> <value>
claude-speak mode               # toggle end ↔ narrate
claude-speak stop               # stop current playback

claude-speak hook stop          # (internal) called by Claude Code Stop hook
claude-speak hook pre-tool      # (internal) called by Claude Code PreToolUse hook

---

Configuration

All settings can be overridden with environment variables or set persistently:

claude-speak config set voice_en en-GB-SoniaNeural
claude-speak config set speak_mode narrate
claude-speak config set max_chars 800

Key	Env var	Default	Description
speak_mode	CLAUDE_SPEAK_SPEAK_MODE	end	end · narrate
speaker_only	CLAUDE_SPEAK_SPEAKER_ONLY	false	Speak only the 🔊 Speaker: line
backend	CLAUDE_SPEAK_BACKEND	edge	edge (online) · system (offline)
voice	CLAUDE_SPEAK_VOICE	(unset)	Override both EN and ES voices
voice_en	CLAUDE_SPEAK_VOICE_EN	en-US-AriaNeural	English voice
voice_es	CLAUDE_SPEAK_VOICE_ES	es-MX-DaliaNeural	Spanish voice
rate	CLAUDE_SPEAK_RATE	0	Speed offset: Edge uses percent (-50..100)
max_chars	CLAUDE_SPEAK_MAX_CHARS	1200	Truncate responses longer than this
wake_word	CLAUDE_SPEAK_WAKE_WORD	(unset)	Require this phrase before speaking
focus_pattern	CLAUDE_SPEAK_FOCUS_PATTERN	(unset)	Regex — only speak if active window matches

---

Voices

List all available Edge voices:

claude-speak voices

Set your preferred voice:

claude-speak config set voice_en en-GB-RyanNeural    # British male
claude-speak config set voice_es es-ES-ElviraNeural  # Spain Spanish female

Language is detected automatically per response (EN/ES). Set voice (not voice_en/voice_es) to force a single voice for all languages.

---

Status line

Add the current mode to your Claude Code status bar:

claude-speak install-statusline

Shows 🔊 end, 🔊 narrate, or 🔇 off depending on active hooks.

---

Diagnostics

claude-speak doctor

Checks: Python version, pygame playback, Edge TTS connectivity, hooks registered in ~/.claude/settings.json, slash commands installed.

---

Uninstall

# Remove hooks + slash commands (keeps package installed)
claude-speak uninstall

# Remove the package entirely
pipx uninstall claude-speak

---

License

MIT