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 out and the hook runs for every notification type, including idle_prompt.

In a terminal session, Notification waits until you seem to be away: permission_prompt plays once you have not typed for about six seconds, and each keystroke pushes it back. 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. The field and command match the Stop input in the hooks reference (checked October 2026).

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.

Run each command once in your own shell before relying on it, on every platform. Sound files and speech packages vary by macOS version, Linux 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 · Test it

Test it in 30 seconds.

Check each link in the chain once, in this order, so you know which part to fix if something stays quiet.

• Run the sound command on its own, for example afplay /System/Library/Sounds/Glass.aiff. No sound here means the problem is your audio setup, not Claude Code.
• Start Claude Code and type /hooks. Your Stop and Notification hooks should be listed under their events.
• Ask Claude to do something that needs approval, such as running a shell command you have not allowed. Switch to another window and stop typing. After about six seconds the “needs you” tone plays.
• Approve it and let the turn finish. The “done” tone plays when Claude stops responding.

(5)When the turn fails

Play a different sound when the turn fails.

Stop does not fire when you interrupt Claude, and a turn that ends on an API error, such as a rate limit, an overloaded server or a login problem, fires StopFailure instead. Without a hook for it, a failed turn is silent and you come back expecting finished work.

Give StopFailure its own sound, distinct from “done”. Claude Code ignores this hook’s output and exit code, so it can only make a noise or log something; it cannot retry the turn. Its payload has an error field (rate_limit, server_error, authentication_failed and others) that you can use as a matcher if you only care about some errors.

{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          { "type": "command", "command": "afplay /System/Library/Sounds/Basso.aiff" }
        ]
      }
    ]
  }
}

(6)Event timing

When each event fires.

Each event fires at a different moment, so pick the one that matches what you want to hear. Timings are from the hooks reference (checked October 2026).

If six seconds is too slow for approvals, a PermissionRequest hook fires the moment Claude asks. Keep it to a sound with "async": true, as in the example below. Claude Code does not run it for a sandboxed command’s network request; permission_prompt still covers that.

• Claude finishes responding (not when you interrupt it)Stop
• The turn ends on an API error, instead of StopStopFailure
• The moment Claude asks to use a toolPermissionRequest
• A permission prompt waits about 6 seconds; in a terminal, typing resets the waitpermission_prompt
• About 60 seconds after Claude finishes, if you have not typedidle_prompt
• A background session finishes or fails, while agent view is openagent_completed

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "async": true, "command": "afplay /System/Library/Sounds/Funk.aiff" }
        ]
      }
    ]
  }
}

(7)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.

• Leave SubagentStop unhooked. It fires every time a subagent finishes, which is constant noise during a large task.
• Speak the folder name so you know which session finished: every payload includes cwd, so jq -r .cwd | xargs basename | say works.
• Want a different signal for approvals, questions and idle prompts? Split the Notification hook by type, as in the needs-input guide.
• Want no hooks at all? Set "preferredNotifChannel": "terminal_bell" for a plain bell in any terminal (docs).

(8)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 normally picks up hook edits on its own, so you do not need to restart; a JSON syntax error is the usual cause.
• Silent after an error? Stop does not fire on API errors or when you interrupt the turn. Add a StopFailure hook as shown above.
• In the VS Code extension and Claude Desktop, hooks come from the same ~/.claude/settings.json as the CLI. Since Claude Code v2.1.233, permission_prompt fires there about six seconds after Claude asks, unless you answer first; before that it did not fire at all. Set CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1 to turn it off there (docs).
• 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.

(9)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.