How to make Claude Code read its progress out loud on your Mac.

(1)Progress vs. done

Which hook fires when.

Claude Code runs hooks on lifecycle events. The usual read-aloud recipe uses Stop, which only fires once Claude has finished responding, so you hear nothing during a long run. These are the events in the hooks reference that are most useful for speech while Claude works, plus the two that tell you it needs you or has stopped.

• MessageDisplay: while Claude’s message text streams to the screen, in batches of whole lines. The input carries message_id, index (the batch number, from 0), final (true on the last batch) and delta (the new lines). It has no matcher, and replies that are only tool calls do not trigger it.
• PostToolUse: after each tool call succeeds. The matcher filters on tool name, such as Bash or Edit|Write, and the input includes tool_name and tool_input. Speaking every call gets noisy fast.
• TaskCompleted: when a task on Claude’s task list is marked completed. The input includes task_subject, the task’s title. It only fires in sessions that have the task tools (see Option 2).
• Notification: when Claude needs you, for example a permission prompt you have not answered for about six seconds (set one up).
• Stop: when Claude finishes responding. Use it for “done”; the sound-when-done guide covers chimes and speech.

(2)Speak as it works

A MessageDisplay hook that reads the start of each message.

This hook speaks the first batch of every message Claude writes, capped at 200 characters, so you hear how each update starts while the run continues. It reads the batch with index 0 rather than the one marked final: in interactive sessions the final batch only carries the last lines of the message, and the reference says it is empty when the message ends on a newline.

Keep "async": true. Per the hooks reference, Claude Code holds each batch of text on screen until a MessageDisplay hook returns, and async runs a command hook in the background so speech never delays the display. The config follows the hooks reference as checked in October 2026; run /hooks afterwards and confirm it is listed under MessageDisplay. If it is not, update Claude Code.

• Every message starts its own say, so two messages close together can talk over each other.
• say reads text literally. The command strips * and #, but file paths and code still come through as written.
• In claude -p runs the hook fires once per message with the whole text at index 0, so the 200-character cap matters more there.

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "jq -r 'select(.index == 0) | .delta | gsub(\"[*#]\"; \"\")' | head -c 200 | say"
          }
        ]
      }
    ]
  }
}

(3)Speak finished tasks

A TaskCompleted hook for a quieter signal.

If hearing every message is too much, speak only when Claude ticks off a task on its task list. On a multi-step job that gives you one short line per finished step, such as “Done: Implement user authentication”.

Check one thing first. The tools reference says the task tools are on by default only on some models; on others Claude keeps no task list, so this hook never fires. Start Claude Code with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude to turn them on. TaskCompleted also fires when an agent team teammate finishes its turn with tasks still in progress.

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "jq -r '\"Done: \" + .task_subject' | say"
          }
        ]
      }
    ]
  }
}

(4)Built in

Desktop app, voice mode and screen readers.

Claude has a few speech features of its own. None of them speaks Claude Code CLI progress on its own. Screen reader mode comes closest if you already use VoiceOver.

• Claude desktop app: some users report a play button that appears when you hover over a response in the Code tab and reads it aloud when you click it; not everyone sees it yet (#58429). It is on demand, not automatic.
• Voice mode: Anthropic’s help center says that in Claude Cowork and Claude Code, dictation is available but voice mode is not. Voice mode is for chats on mobile, desktop and the web.
• Screen reader mode: claude --ax-screen-reader prints labeled lines such as claude: and tool: that VoiceOver reads in order, and rings the terminal bell when Claude finishes a reply, when a prompt needs your answer, and when a tool that ran longer than 5 seconds finishes (accessibility docs).

(5)Plugins

Tools that narrate for you.

If you would rather not write hooks, these open-source projects install them for you. Each is free under MIT and speaks with a local voice by default. Where they beat Heard is platform: claude-code-narrator also supports Linux (its author has not yet verified Linux audio), and claude-read-aloud runs on Linux and Windows and adds a speaker button inside Claude Code’s VS Code chat box, while Heard runs on macOS only. The text-to-speech comparison puts them side by side.

• claude-code-narrator: a Claude Code plugin that speaks a short line for each tool step, the text between tool calls, the opening of the final reply and notifications, with a local Kokoro voice on macOS or Linux. The closest match to “read its progress out loud”.
• Aloud: local Kokoro speech on macOS for Claude Code and Codex. It speaks questions, approval requests, blockers and a short gist of each completed reply, and keeps routine tool calls silent.
• claude-read-aloud: a plugin plus a VS Code extension that puts a speaker button in Claude Code’s chat box. It reads replies on demand or automatically, with system voices or a local Kokoro voice. The in-chat button is opt-in because it patches the installed Claude Code extension.

(6)A voice layer

Heard: summaries instead of a readout.

The hooks above read Claude’s own words, and the plugins mostly do too: claude-code-narrator speaks a short line per tool step, and Aloud trims each reply to a short gist. Heard decides what is worth saying across all your sessions: it summarizes progress and tool activity into a sentence or two, and makes sure questions, approvals, blockers, failures and final results come through. With several Claude Code or Codex sessions running, it keeps each session’s context separate and batches routine activity into short summaries that start with the project name. On Heard Power you can answer back by voice.

The engine is open source under Apache 2.0 and speaks with a local Kokoro voice. The Mac app is the managed build, needs macOS 14 or later, and installs its Claude Code hook for you. Every new account starts with a 14-day Heard Power trial, no card required; see pricing for the plans.

• Summaries, not a transcript read aloud.
• Several sessions, one voice.
• Answer back on Power.
• macOS 14 or later; open-source engine available.

git clone https://github.com/heardlabs/heard
cd heard
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
heard install claude-code