Claude Code already notifies you when it finishes, in some terminals: Ghostty and Kitty show a desktop notification, iTerm2 does once you turn its alerts on, and the others get a bell or nothing. For a sound or a banner in any terminal, the moment a reply finishes, add a Stop hook. Both tell you that something finished. Neither tells you which session or what it did, which is the part you need when you run several.
Checked against Claude Code's own docs on 4 November 2026.
Does Claude Code notify you when it's done?
Yes, when you seem to be away from the terminal. When Claude finishes a task or waits for a permission prompt and you haven't been typing, it sends a notification. What you get depends on the terminal (docs):
| Terminal | What you get when Claude finishes |
|---|---|
| Ghostty, Kitty | A desktop notification, no setup |
| iTerm2 | A desktop notification after you turn on its alerts (below) |
| Apple Terminal | No sound by default: a silent bell, or nothing |
| Warp, the VS Code terminal | No desktop notification. Use a hook, or the terminal bell |
| Inside tmux | Nothing reaches the outer terminal until you set allow-passthrough |
iTerm2: Settings → Profiles → Terminal → check "Notification Center Alerts", then Filter Alerts → turn on "Send escape sequence-generated alerts".
Any terminal, as a bell: add this to ~/.claude/settings.json. In Apple Terminal, also turn on Settings → Profiles → Advanced → Audible bell.
{ "preferredNotifChannel": "terminal_bell" }
Stop or Notification: which hook fires when?
This trips up most setups. Use Stop for "it's done" and Notification for "it needs me".
| Hook | Fires | Good for |
|---|---|---|
Stop |
The moment the main agent finishes a reply. Not when you interrupt with Esc. | A sound, banner or voice when it's done |
Notification, idle_prompt |
About 60 seconds after Claude finished, if you haven't typed since | "You forgot about me" |
Notification, permission_prompt |
When a permission prompt has waited about 6 seconds | "Claude needs an OK" |
If your "done" sound comes a minute late, you've hooked idle_prompt. Move it to Stop.
How do I play a sound when Claude Code finishes?
A Stop hook with afplay, in ~/.claude/settings.json:
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff", "async": true }
]
}
]
}
}
"async": true runs it in the background, so Claude never waits for the sound. Any file in /System/Library/Sounds works: Glass, Ping, Hero, Submarine.
How do I get a Mac banner that names the project?
The Stop hook's input includes cwd, the session's folder, and last_assistant_message, the reply. This script shows a banner titled with the folder name and the reply's first line, then plays a sound. Save it as ~/.claude/hooks/done.sh and run chmod +x on it:
#!/bin/bash
# Banner and sound when a Claude Code reply finishes, with the project name (macOS).
input=$(cat)
# Claude is continuing because of another Stop hook, or background work is still running: wait for the real end.
[ "$(jq -r '.stop_hook_active' <<<"$input")" = "true" ] && exit 0
[ "$(jq '.background_tasks // [] | length' <<<"$input")" -gt 0 ] && exit 0
project=$(basename "$(jq -r '.cwd' <<<"$input")")
first=$(jq -r '.last_assistant_message // "" | split("\n")[0] | .[0:120]' <<<"$input")
osascript - "$project" "$first" <<'APPLESCRIPT'
on run argv
display notification (item 2 of argv) with title "Claude Code: " & (item 1 of argv) & " is done"
end run
APPLESCRIPT
afplay /System/Library/Sounds/Glass.aiff &
exit 0
Then point the Stop hook at it:
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/done.sh", "async": true }
]
}
]
}
}
No banner? osascript notifications come from Script Editor, and macOS doesn't ask for permission. Run osascript -e 'display notification "test"' once, then System Settings → Notifications → Script Editor → Allow Notifications.
jq is built into macOS 15 and later. The background-tasks check matters: when Claude starts a long job in the background it ends its turn with "Started the build", and without the check you get a "done" banner for work that hasn't happened yet.
How do I make it say which project finished?
Swap the banner for the Mac's voice: say "$project is done" &. Or read the reply itself; this Stop hook reads it aloud and lists everything that goes wrong when you do.
When is a chime not enough?
With one session, a chime is all you need. With four, it stops working:
- A ding doesn't say what happened. You still walk back and read 40 lines to find out whether the tests passed.
- Banners pile up. Three "review-app is done" banners, and you don't know which one is new.
- Away from the screen, a banner is useless. You're in the kitchen; you hear Glass, and that's all you get.
This is what I built Pintail for. When a reply finishes, it speaks a short summary of what happened (one sentence up to the whole reply, your pick), and a pill in the notch names the project, with live captions. Replies from several sessions play one at a time, in the order they finished. Automatic reading is off until you turn it on. It costs $15 once with 20 free read-outs, and needs no account. Other ways to hear the replies, several of them free, are compared side by side.
Which should you use?
- One session, at the desk: the built-in notification, or the
afplayStop hook. - Several sessions: the banner script, so you see the project name.
- Away from the desk, or tired of reading: a spoken summary. Pintail or one of the free tools.
- Claude waiting on you without you noticing: a Notification hook on
permission_prompt.