Get notified when Claude Code finishes

Updated

Quick answer

Claude Code can tell you when it is done through a Stop hook: a command in ~/.claude/settings.json that runs the moment Claude finishes responding. Point it at your system’s notification command for an alert on the computer, or at a push service for an alert on your phone. Add a Notification hook for the other case, when Claude is waiting for you rather than finished.

What Claude Code does on its own

Without any setup, Claude Code alerts you only in some terminals, and only when you seem to be away from the terminal:

Setting "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json makes Claude Code ring the bell in any terminal. It is a start, but the built-in alert follows the same timing as the Notification hook below, so the end-of-task alert comes about a minute after Claude finishes, and it says nothing about what Claude did. A Stop hook fires at the end of every turn and can show Claude’s last message.

The Stop hook in five lines

A hook is a command Claude Code runs at a fixed moment. Stop runs when the main agent finishes responding. It has no matcher: it fires on every turn. Add it to ~/.claude/settings.json, next to any hooks you already have:

~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/done.sh" }] }
    ]
  }
}

The hook receives the session as JSON on standard input, including cwd and last_assistant_message, the text of Claude’s final reply. Use that field rather than reading the transcript, which can lag behind. This script turns it into a macOS notification titled with the project:

Save as ~/.claude/hooks/done.sh, then chmod +x it (needs jq)

#!/bin/sh
# Stop hook: a desktop notification with the project and what Claude just said.
input=$(cat)
# A subagent still running in the background: wait for the real end.
[ "$(printf '%s' "$input" | jq '[.background_tasks[]? | select(.type=="subagent")] | length')" -gt 0 ] && exit 0
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
msg=$(printf '%s' "$input" | jq -r '.last_assistant_message // "Finished"' | head -c 180)
osascript -e 'on run argv' -e 'display notification (item 2 of argv) with title (item 1 of argv)' \
  -e 'end run' "Claude Code · $project" "$msg"
exit 0

Three details matter. Stop also fires when a turn ends while a subagent keeps running in the background, and again when it finishes; the background_tasks line skips the first one, so you are told once, at the real end. It counts subagents only: a dev server or a tail -f left running in the background would otherwise silence every alert. It does not fire when you interrupt Claude with Esc. And when a turn ends on an API error, such as a rate limit, Claude Code runs StopFailure instead, which you can point at the same script.

The same hook on macOS, Windows and Linux

Only the line that shows the alert changes:

Swipe the table sideways to see all columns.

SystemCommand in the scriptIf nothing shows
macOSosascript, as aboveSystem Settings › Notifications › Script Editor: turn on Allow Notifications
Linuxnotify-send "Claude Code · $project" "$msg"Install libnotify-bin or your distribution’s equivalent; a server without a desktop has nowhere to show it
WindowsBurntToast’s New-BurntToastNotification, in a hook with "shell": "powershell" (line below)Install the module once (line below)

On Windows, in PowerShell: install once, then the line for the hook

Install-Module BurntToast -Scope CurrentUser
New-BurntToastNotification -Text 'Claude Code', 'Claude finished'

The guides for macOS and Windows add sounds, click to focus, and WSL.

Finished is not the same as waiting

Stop means the turn is over. When Claude stops in the middle of a turn, at a permission prompt, a multiple-choice question or a form from an MCP server, no Stop fires: the turn is still open. That case belongs to the Notification hook. Its permission_prompt type fires once a prompt has waited about six seconds without you typing, and idle_prompt about 60 seconds after Claude finished, if you haven’t typed since.

Add to the same hooks object

"Notification": [
  {
    "matcher": "permission_prompt|elicitation_dialog",
    "hooks": [{ "type": "command", "command": "~/.claude/hooks/waiting.sh" }]
  }
]

A Notification hook receives a message such as “Claude needs your permission”, which waiting.sh can show the same way. To be told the instant a permission is asked rather than six seconds later, use PermissionRequest. The Notification hook and the Stop hook cover each event in detail.

Get the alert on your phone

A desktop notification only helps if you are at the desk. Three ways to carry the same moment to your phone:

Questions

Why does my Stop hook fire several times during one task?
Stop runs at the end of every turn, not of the whole task, and also when a turn ends while a subagent is still running in the background. Skip the alert while background_tasks lists a task of type subagent, and ignore the other types, such as a dev server left running.
Does the Stop hook run when I press Esc?
No. Claude Code doesn’t run Stop when you interrupt it. When a turn ends on an API error, it runs StopFailure instead.
Can I hear a sound instead of a notification?
Yes. Run a sound player from the same hook, such as afplay /System/Library/Sounds/Glass.aiff on macOS, or set preferredNotifChannel to terminal_bell to ring the terminal’s bell.
Will the hook slow Claude Code down?
No. It runs once the turn is over, and a notification command returns in well under a second. Claude Code cancels a command hook after 600 seconds by default.

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