debrief

Debrief

Hear and follow along with Claude Code responses. A floating, always-on-top read-along panel — Apple Music-style word highlight using your macOS system / Siri voice — plus attention chimes when a response is ready or an approval is needed. Handy when you're running several agents at once and need to notice which one wants you.

macOS + Claude Code. The read-along panel reads Claude Code's session transcript directly; the chimes are plain shell scripts and work with any macOS CLI that supports shell hooks.

What you get

• /say — opens a floating read-along panel. Each word highlights as it's spoken. Floats above every fullscreen app and uses your system / Siri voice. Controls: play/pause, previous/next sentence, click-to-jump, speed slider.
• /say audio — audio-only (no panel).
• /say full — reads the entire response from the top (default reads the last part only, which is usually what you want).
• Chimes — a Glass sound when Claude finishes a response and a Notification sound when Claude needs your approval, so you can hear which agent wants you without looking at the screen.

Requirements

• macOS
• Claude Code CLI
• Xcode Command Line Tools for the native panel: xcode-select --install
  Without them, /say falls back to a browser popup automatically — no errors.

Install

Option A — Plugin marketplace (recommended)

Open Claude Code in the cloned folder and run:

/plugin marketplace add /absolute/path/to/say-aloud
/plugin install debrief@debrief

Restart Claude Code, then approve the plugin's hooks when prompted (or run /hooks to approve them manually).

Option B — Manual (wire hooks directly)

Add three entries to ~/.claude/settings.json under "hooks":

"UserPromptSubmit": [
  { "matcher": "", "hooks": [
    { "type": "command",
      "command": "python3 \"/path/to/say-aloud/plugins/debrief/scripts/debrief_hook.py\"" }
  ]}
],
"Stop": [
  { "matcher": "", "hooks": [
    { "type": "command",
      "command": "bash \"/path/to/say-aloud/plugins/debrief/scripts/chime.sh\" stop",
      "async": true }
  ]}
],
"Notification": [
  { "matcher": "", "hooks": [
    { "type": "command",
      "command": "bash \"/path/to/say-aloud/plugins/debrief/scripts/chime.sh\" notify",
      "async": true }
  ]}
]

Then install the /say command so Claude Code knows about it:

cp /path/to/say-aloud/plugins/debrief/commands/say.md ~/.claude/commands/say.md

Restart Claude Code for hooks to take effect.

Commands

Command	What it does
/say	Open the read-along panel (last part of response)
/say full	Panel reading the entire response from the top
/say audio	Read aloud only, no panel (last part)
/say audio full	Read the entire response aloud, no panel
/say web	Force the browser popup instead of the native panel
/say stop	Stop any in-progress speech
/say voice NAME	Set and persist the voice — plays a sample
/say rate WPM	Set and persist the speech rate in words per minute
/say browser NAME	Set the browser used for the popup
/say voices	List installed English voices
/say config	Show current settings
/say reset	Clear saved settings and go back to defaults

Panel controls

Key / action	What it does
Space	Play / pause
← →	Previous / next sentence
R	Restart from the top
Click a sentence	Jump to that sentence
Speed slider	Adjust playback rate live
Esc	Close

Configuration

Settings live in ~/.claude/say.conf, created automatically on first use:

voice=Ava
rate=200
browser=Google Chrome

All three keys are optional. To use your Siri voice, set it in System Settings → Accessibility → Spoken Content → System Voice and leave voice unset — Debrief picks up the system voice automatically through say with no -v flag.

voice accepts any name from /say voices. rate is in words per minute (150–260 is a typical range). browser can be Google Chrome, Brave, Microsoft Edge, Chromium, or any other browser name — non-Chromium browsers open as a normal tab rather than a chromeless popup.

First run: panel compilation

On the first /say, Debrief compiles debrief_panel.swift into a native binary using swiftc (part of Xcode Command Line Tools). This takes a few seconds. The binary is gitignored and not distributed. If compilation fails for any reason, /say falls back to the browser popup silently.

Using the chimes with other CLIs