Hooks / notifications

Notify when the agent completes

Desktop notification when Claude finishes a turn - useful for long unattended runs.

What it does

Fires on Notification with the agent_completed matcher and posts a native desktop notification. Pairs well with headless or background sessions you check on between other work.

When it runs

Config

Merge this into .claude/settings.json (or ~/.claude/settings.json for user scope) - or use the generator to combine hooks.

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify-agent-complete.sh",
            "timeout": 10,
            "async": true
          }
        ],
        "matcher": "agent_completed"
      }
    ]
  }
}

Script

Save as .claude/hooks/notify-agent-complete.sh and chmod +x it.

#!/bin/bash
# notify-agent-complete: desktop notification on agent completion.
set -u
msg="Claude finished"
if command -v osascript >/dev/null 2>&1; then
  osascript -e "display notification \"$msg\" with title \"Claude Code\"" >/dev/null 2>&1 &
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code" "$msg" >/dev/null 2>&1 &
fi
exit 0

Install

1. Save the script to .claude/hooks/notify-agent-complete.sh and chmod +x it.
2. Add the config fragment to ~/.claude/settings.json.

Test it

• Positive: run a short task - a notification fires when the turn completes.
• Negative: mid-turn tool calls should not notify.

Sources

• Claude Code hooks reference (checked 2026-09-10)

Related hooks