How to make Claude Code play a sound or speak when it finishes.

(1)Step 1 · macOS sound

Play a sound when Claude finishes or needs you.

Add both hooks to ~/.claude/settings.json, or to .claude/settings.json inside a repo to scope them to that project. The permission_prompt matcher limits the Notification hook to permission requests, so the “needs you” tone always means you have a decision to make. Leave the matcher empty to also hear idle_prompt, which fires when Claude has been waiting on you.

Claude Code only fires Notification when you appear to be away from the terminal, so use Stop as your completion signal: it fires at the end of every turn. Any file in /System/Library/Sounds works. Glass and Funk are different enough to tell apart without looking.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Funk.aiff" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }
        ]
      }
    ]
  }
}

(2)Step 2 · Speech

Make Claude Code say what it did.

Every Stop hook receives a JSON payload on stdin, and its last_assistant_message field holds the text of Claude’s final reply. Pipe it through jq into a text-to-speech command and Claude Code reads its own result aloud. We checked the payload and this exact command against Claude Code 2.1.288.

Cap the length. A final message can be a long report, and say reads every word, including file paths and code. 300 characters is usually one or two sentences. "async": true lets Claude Code carry on while the voice is still speaking.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "jq -r '.last_assistant_message // empty' | head -c 300 | say"
          }
        ]
      }
    ]
  }
}

(3)Step 3 · Linux and Windows

The same two hooks on Linux and Windows.

The hook shape is identical on every platform; only the commands change. On Linux, paplay plays the freedesktop sounds through PulseAudio or PipeWire, and spd-say speaks text. On Windows, PowerShell plays a WAV with System.Media.SoundPlayer and speaks with System.Speech.

We tested the macOS commands end to end. Run the Linux and Windows commands once in your own shell before relying on them, because sound files and speech packages vary by distribution and Windows edition.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/dialog-warning.oga" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga" },
          { "type": "command", "async": true, "command": "spd-say \"$(jq -r '.last_assistant_message // empty' | head -c 300)\"" }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          { "type": "command", "command": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:/Windows/Media/Windows Notify System Generic.wav').PlaySync()\"" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:/Windows/Media/tada.wav').PlaySync()\"" },
          { "type": "command", "async": true, "command": "powershell -NoProfile -Command \"Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('Claude Code finished')\"" }
        ]
      }
    ]
  }
}

(4)Step 4 · Noise control

Only make noise when it matters.

Two distinct sounds are the right default. If you run long or parallel sessions, tighten the rules so every sound still means something.

• Match permission_prompt only if idle_prompt reminders start to feel like nagging.
• Leave SubagentStop unhooked. It fires every time a subagent finishes, which is constant noise during a large task.
• Expect idle_prompt to arrive a while after Claude stops; permission prompts fire right away. Use Stop for “done”.
• Speak the folder name so you know which session finished: every payload includes cwd, so jq -r .cwd | xargs basename | say works.
• Want no hooks at all? Set "preferredNotifChannel": "terminal_bell" for a plain bell in any terminal (docs).

(5)Troubleshooting

If the hook stays silent.

Most silent hooks come down to one of these causes.

• Run the command by itself first. If afplay /System/Library/Sounds/Glass.aiff is silent in your terminal, fix the output device or volume before touching hooks.
• Run /hooks inside Claude Code to see what loaded. Claude Code watches settings files and reloads hooks on its own, so you do not need to restart; a JSON syntax error is the usual cause.
• In the VS Code extension, Notification hooks have been reported not to fire for in-panel prompts (#26925). The Stop hook still works there.
• Over SSH, hooks run on the remote machine, so afplay plays on the server. Claude Code’s built-in desktop notification does reach your laptop in Ghostty, Kitty and iTerm2.
• Inside tmux, add set -g allow-passthrough on to ~/.tmux.conf so notifications reach the outer terminal.
• On Windows, use PlaySync() as in the example above: it waits for the sound to finish. Play() returns at once and PowerShell exits before you hear anything.
• On Linux, paplay plays WAV and OGG. For MP3, use mpg123 or ffplay -nodisp -autoexit instead.
• In Apple Terminal, /terminal-setup turns the audible bell off. Turn it back on under Settings → Profiles → Advanced if you rely on terminal_bell.

(6)Beyond a chime

When a chime is not enough: a voice layer.

A chime tells you that something happened. say tells you what Claude wrote, word for word. Neither tells you which of four sessions just stopped, or whether it stopped because tests failed or because the work is done.

Heard is a voice layer for coding agents on macOS. It connects to Claude Code and Codex through native adapters, decides what deserves airtime (questions, blockers, failures, results), and says it in a sentence or two. With several sessions running, it batches routine activity into short summaries that start with the project name. On Power you can answer back by voice or from your iPhone. The engine is open source under Apache 2.0 with a local Kokoro voice, and every new account starts with a 14-day Power trial, no card required.