claude-code-tts-setup

Read Claude Code responses aloud on macOS, using the built‑in say command driven by Claude Code hooks. On/off is controlled per working directory, so you can have it speak in one project and stay silent in another.

日本語の方へ: 既定は英語の音声/文言ですが、~/.claude/tts.conf で日本語ボイス（Kyoko など）と日本語の文言に切り替えられます。例は tts.conf.example 参照。

What it does

• 🔊 Reads each assistant message aloud as it appears.
• 🧵 Serial queue — one utterance at a time. No overlapping voices, no getting cut off mid‑sentence (the two failure modes a naive say & hook runs into).
• 📁 Per‑directory on/off with inheritance — set it at a project root and every subdirectory follows. Stored in <project>/.claude/tts.local.
• 🔔 Notification chime + spoken "input needed" cue when Claude is waiting on you.
• ⚙️ Configurable voice, rate, language, and phrases via ~/.claude/tts.conf.
• 🗣️ Swappable speech backend — use macOS say, or a more natural voice such as a LAN AivisSpeech engine (see docs/aivisspeech-engine-setup.md).

Requirements

• macOS (uses say and afplay)
• jq — brew install jq
• Claude Code

Quick start

git clone https://github.com/aitit-inc/claude-code-tts-setup.git
cd claude-code-tts-setup
./install.sh

Then restart Claude Code, go into a project, and run:

/tts-on      # enable read-aloud for this directory
/tts-off     # turn it off again

TTS is off by default everywhere until you /tts-on in a directory. See SETUP_GUIDE.md for manual install, configuration, how it works, and troubleshooting.

How on/off is resolved

1. Nearest <dir>/.claude/tts.local walking up from the project root (on/off).
2. Otherwise the global default flag ~/.claude/state/tts-enabled (present = on).

Uninstall

./uninstall.sh

License

MIT — see LICENSE.