Get a desktop ping when Claude Code is waiting on you, with a Notification hook

You kick off a long Claude Code task, switch to another window, and come back twenty minutes later to find it stopped after two minutes, waiting for you to approve one command.

A Notification hook fixes that. Claude Code fires it when it needs your attention, such as a permission prompt or an idle wait for input, and the hook receives a small JSON payload on stdin with a message field.

The script

Save as .claude/hooks/notify.sh and chmod +x it:

#!/usr/bin/env bash
# notify.sh: desktop ping when Claude Code needs you
set -uo pipefail
msg=$(python3 -c 'import sys,json; print(json.load(sys.stdin).get("message","Claude Code needs you"))' 2>/dev/null || echo "Claude Code needs you")
if command -v osascript >/dev/null; then
  osascript -e "display notification \"${msg//\"/}\" with title \"Claude Code\""
elif command -v notify-send >/dev/null; then
  notify-send "Claude Code" "$msg"
else
  printf '\a'  # terminal bell as a last resort
fi
exit 0

Register it

In .claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": ".claude/hooks/notify.sh" }
        ]
      }
    ]
  }
}

Check the hooks page for your installed Claude Code version; payload fields and matcher options can change between releases.

Keep it useful

• Always exit 0. A notification hook should never block the session.
• Pair it with a sensible allow-list in settings.json, so you get pinged for decisions that matter, not for every ls.
• Keep the message short. You want to know which repo is waiting, not read a log.

I keep this hook alongside the allow-list, the safety hooks, and a short house-rules file in Vildanden Agent Config. The free sample has enough to try the pattern today.