Speak Claude Code's replies aloud on macOS using the built-in say command, and get a spoken heads-up when Claude needs you. Everything is controlled live by the /say:aloud command — on/off, voice, speed, code-block handling, and alerts — with no restart.
Three hooks do the work:
- Stop — reads each finished reply (markdown cleaned so it sounds natural), non-blocking.
- UserPromptSubmit — stops the current readout the instant you send a message.
- Notification — speaks an alert when Claude is waiting on you or needs permission.
macOS only. Uses
/usr/bin/sayand the system Perl (JSON::PP), both preinstalled.
/plugin marketplace add B1G/say-plugin
/plugin install say@b1g
Reload plugins (or restart the session), then turn it on:
/say:aloud on
Toggle the whole plugin anytime from /plugin — no settings.json editing.
| Command | Effect |
|---|---|
/say:aloud on · off |
Enable / disable spoken responses |
/say:aloud stop |
Stop the current readout immediately |
/say:aloud repeat |
Replay the last readout (aliases: replay, again) |
/say:aloud status |
Show state: voice | say-voice | rate | code | attention |
/say:aloud voice <name> |
Set voice (e.g. voice Daniel; multi-word names ok) |
/say:aloud voices |
List installed English voices with accent + sample |
/say:aloud try [name] |
Play a spoken preview (one voice, or a curated set) |
/say:aloud faster · slower |
±25 wpm (starts at 175, floor 80) |
/say:aloud rate <wpm> |
Exact speed · rate reset → voice's native rate |
/say:aloud code announce|read|off |
Fenced code: say "code block." / read aloud / skip |
/say:aloud attention on|off |
Spoken alerts when Claude needs you (alias attn · reset → follow voice) |
Recommended flow: /say:aloud voices → /say:aloud try Daniel → /say:aloud voice Daniel.
The Notification hook speaks a short alert when Claude Code pings you — waiting for input, or asking permission (e.g. "Claude needs your attention"). It's controlled by attention, which is independent of response reading:
- Default — alerts follow the voice toggle: on whenever
/say:aloud onis set. /say:aloud attention off— mute alerts but keep reading replies./say:aloud attention onwith voice off — alerts-only mode: Claude stays quiet on normal replies but still pings you when it needs you./say:aloud attention reset— back to following the voice toggle.
Your settings live in ~/.claude/ and survive plugin updates — the plugin only ships code, never your prefs:
| File | Meaning |
|---|---|
say.on |
presence = spoken responses enabled |
say.voice |
voice name (default Samantha) |
say.rate |
words per minute (default: voice's native rate) |
say.code |
fenced-code mode: announce / read / off |
say.attention |
alerts: on / off (absent = follow say.on) |
say.last |
last spoken text (used by repeat) |
say.skip |
internal one-shot flag so a command's own echo isn't spoken/saved |
say.replay |
internal one-shot flag; tells the Stop hook to replay say.last |
Stop a readout with /say:aloud stop, killall say from any shell, or just send your next message — a new prompt auto-cuts the previous one.
Speaks only the final assistant text of a turn (omits your prompts, tool calls, and thinking). Inline code → spoken as words; links → their text; bare URLs → "link"; slash-commands verbalized (/say:aloud → "slash say colon aloud"); bold/italic markers stripped (list bullets kept); fenced code announced / read / skipped per say.code.
- macOS (for
/usr/bin/say) - System Perl with
JSON::PP(perl -MJSON::PP -e1should be silent)
MIT © M. Benjamin Yusuf