Play a sound when Claude Code finishes

Updated

Quick answer

To hear a sound when Claude Code finishes, either set preferredNotifChannel to terminal_bell so Claude Code rings your terminal’s bell, or add a Stop hook that plays a sound file with afplay, paplay or PowerShell. The bell depends on your terminal’s settings. The hook works everywhere.

The built-in bell

Claude Code can alert you by itself when a task completes or a permission prompt is waiting. The preferredNotifChannel setting, shown as Local notifications in /config, decides how. Its default, "auto", sends a desktop notification in iTerm2, Ghostty and Kitty, and stays silent in most other terminals. To get a sound, ask for the bell character instead:

In ~/.claude/settings.json

{
  "preferredNotifChannel": "terminal_bell"
}

Other values: "iterm2_with_bell" sends an iTerm2 notification and rings the bell, and "notifications_disabled" turns Claude Code’s own alerts off without stopping your hooks.

Know the timing before you rely on it. The built-in alert follows the rules of Claude Code’s notifications: you only get it when you appear to be away from the terminal. A permission prompt rings after about six seconds without a keystroke. A finished task rings about sixty seconds after Claude stops, and only if you haven’t typed since. If you want the sound the moment Claude finishes, use the hook below.

Terminal by terminal

The bell character is a request; your terminal decides what to do with it.

TerminalTo hear the bell
Apple TerminalTurn on Audible bell in Settings › Profiles › Advanced. If you accepted Claude Code’s first-run terminal setup, it turned that option off.
iTerm2Make sure the profile doesn’t silence the bell, or use "iterm2_with_bell" to get the notification and the sound.
Ghostty, KittyWith "auto" you get a desktop notification; switch to "terminal_bell" and check the terminal’s bell options for a sound.
Windows TerminalSet the profile’s bell style to audible.
VS Code, CursorTurn on the integrated terminal’s bell sound in the editor settings; search for “terminal bell”.
tmuxtmux flags the window that rang in its status line. Whether the sound reaches you depends on your tmux bell options and the terminal around it.

If the bell stays silent after that, the hook is the fix: it doesn’t depend on the terminal at all.

A Stop hook that plays a sound

A Stop hook runs each time Claude finishes responding, at once. It can play any sound file. Mark it async so Claude Code doesn’t wait for the sound to end:

macOS, in ~/.claude/settings.json

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

The same hook on the other systems, with only the command changed:

On macOS, the files in /System/Library/Sounds include Glass, Hero, Ping, Pop and Submarine. Run the command alone in a terminal first: if you hear nothing there, the hook won’t make a sound either. Then check that /hooks lists it.

Stop runs after every reply, including a one-line answer. To hear only the end of long turns, note the time when you send a prompt and compare it when Claude stops. A UserPromptSubmit hook writes the time, keyed by session; the Stop hook plays only after a minute or more:

Save as ~/.claude/hooks/long-turn.sh, then list it under both events

#!/bin/sh
# Claude Code hook for UserPromptSubmit and Stop: a sound only after turns longer than 60 seconds.
input=$(cat)
f="${TMPDIR:-/tmp}/claude-turn-$(printf '%s' "$input" | jq -r '.session_id')"
if [ "$(printf '%s' "$input" | jq -r '.hook_event_name')" = "UserPromptSubmit" ]; then
  date +%s > "$f"; exit 0
fi
start=$(cat "$f" 2>/dev/null || echo 0)
[ $(( $(date +%s) - start )) -ge 60 ] && afplay /System/Library/Sounds/Glass.aiff
exit 0

A different sound when Claude needs you

“Finished” and “waiting for you” call for different reactions, so give them different sounds. A Notification hook with a matcher plays when Claude is blocked on a permission or on a form from an MCP server:

Merge next to the Stop hook

{
  "hooks": {
    "Notification": [
      { "matcher": "permission_prompt|elicitation_dialog",
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Ping.aiff", "async": true }] }
    ]
  }
}

permission_prompt fires once the prompt has waited about six seconds without a keystroke. For a sound the moment Claude asks, use a PermissionRequest hook instead. A hook on that event that prints nothing makes no decision, so the prompt then appears as usual and you answer it yourself.

When you’re out of earshot

A sound works as far as you can hear your computer. Past that, the moment Claude finishes or needs you has to reach your phone. Monish does it with a push and a sound on your iPhone: Allow or Deny for a permission request, the options for a question, a Reply action on a finished turn. Install the app, then run curl -fsSL https://monish.cc/install.sh | sh -s with the 6-digit code it shows. Quiet hours keep the night silent, and the hooks above can stay where they are.

Questions

Why does the bell ring a minute after Claude finishes?
Claude Code’s own alert for a finished task comes about sixty seconds after Claude stops, and only if you haven’t typed since. A Stop hook plays at once.
Why don’t I hear anything in Apple Terminal?
If you accepted Claude Code’s first-run terminal setup, it turned off the audible bell in your Terminal profile. Turn Audible bell back on in Settings › Profiles › Advanced, and set preferredNotifChannel to terminal_bell.
Will the sound play after every reply?
Yes, with a Stop hook: it runs each time Claude finishes responding, short answers included. Keep only the Notification sound if you want to hear Claude only when it is blocked.
Does a sound hook slow Claude Code down?
A hook without async holds the end of the turn until the command exits. With "async": true, Claude Code carries on while the sound plays.

More guides

New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.

Get Monish on your iPhone

Free, no account. Your 6-digit code is waiting in the app.

Download on the App Store