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.
Save as .claude/hooks/notify.sh and chmod +x it:
#!/usr/bin/env bash
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
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.
exit 0. A notification hook should never block the session. settings.json, so you get pinged for decisions that matter, not for every ls.
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.