De Claude Code Notification hook: wanneer hij afgaat en hoe je hem gebruikt

01De notificatietypes

De matcher op een Notification-hook is het notificatietype. Laat hem leeg om op alle types te draaien, of noem de types die je wilt, gescheiden door |. De types die je waarschijnlijk het vaakst gebruikt:

Er zijn er meer, zoals agent_needs_input en agent_completed voor achtergrondsessies in agent view, en een reeks quota_auto_resume_*-types voor het wachten op gebruikslimieten. De hooks-referentie heeft de volledige, actuele lijst.

02De timingregels

Hier gaan veel mensen de mist in. De Notification-hook deelt zijn timing met de eigen desktopnotificaties van Claude Code, dus in een terminalsessie gaat hij alleen af als je even niet kijkt:

• permission_prompt start een timer van zo'n zes seconden zodra de prompt verschijnt. Elke toetsaanslag zet die timer terug. Antwoord je snel, dan gaat hij nooit af.
• idle_prompt gaat zo'n 60 seconden nadat Claude klaar is af, maar alleen als je sindsdien niets hebt getypt en er geen background agent meer draait. Hij gaat niet af terwijl Claude Code wacht tot een usage limit is gereset.
• Een verzoek dat binnenkomt terwijl er al een ander dialoogvenster open is, wordt getimed vanaf het moment van binnenkomst. De notificatie kan je dus bereiken terwijl het verzoek nog achter het open venster wacht.

Hosts die permissions via de Agent SDK afhandelen, zoals Claude Desktop en de VS Code-extensie, timen permission_prompt anders: zo'n zes seconden na het verzoek, niet uitgesteld door typen, en overgeslagen als jij of een PermissionRequest-hook eerder antwoordt.

Wil je een signaal zonder vertraging, gebruik dan een ander event:

03Wat de hook ontvangt

Naast de standaardvelden (session_id, transcript_path, cwd, hook_event_name) krijgt een Notification-hook de message van de notificatie, een optionele title en het notification_type:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

De message is de eigen tekst van Claude Code, dus die kun je gewoon zo tonen. cwd is handig als je meerdere sessies draait en wilt weten welk project iets vraagt.

04Wat de hook wel en niet kan

Een Notification-hook kan de notificatie niet blokkeren, uitstellen of aanpassen. Zijn exit code en stderr worden genegeerd, en Claude Code negeert systemMessage en continue in de JSON-output. Hij is puur bedoeld voor side effects.

Er is één outputveld dat hij wel kan gebruiken: terminalSequence. Hooks draaien zonder terminal, dus ze kunnen zelf geen escape sequences schrijven, maar ze kunnen er wel een aan Claude Code doorgeven om uit te sturen. Zo kan een hook een native terminalnotificatie triggeren in iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal en meer, zelfs binnen tmux. Dit werkt alleen in een interactieve sessie met de interface van Claude Code op het scherm.

Ook de setting preferredNotifChannel houdt de hook niet tegen. Zelfs met de ingebouwde notificaties uit gaat het Notification-event gewoon af. Die setting bepaalt alleen hoe Claude Code je zelf waarschuwt; zie de handleiding over de terminal bell.

05Voorbeelden

Verschillende handlers per type

Draai een apart script voor permission prompts en voor idle-herinneringen:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-alert.sh" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/idle-alert.sh" }]
      }
    ]
  }
}

Maak elk script uitvoerbaar met chmod +x. De commando's voor desktopnotificaties op Mac, Windows en Linux staan in hoe je een notificatie krijgt als Claude Code klaar is, dus die herhalen we hier niet.

Toon het echte bericht en project

Dit script (macOS en Linux) zet het bericht van Claude Code en de projectmap in de notificatie, in plaats van een vaste tekst:

#!/bin/bash
# ~/.claude/hooks/notify.sh
input=$(cat)
msg=$(jq -r '.message // "Claude Code needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // "."' <<<"$input")")

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'on run argv' \
            -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
            -e 'end run' "$msg" "Claude Code: $project"
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code: $project" "$msg"
fi
exit 0

Door de tekst als argumenten door te geven (on run argv) breekt de AppleScript niet als het bericht aanhalingstekens bevat. Je hebt jq nodig.

Een native terminalnotificatie

Het eigen voorbeeld van Anthropic gebruikt terminalSequence met OSC 777, wat Ghostty, Warp en urxvt begrijpen:

#!/bin/bash
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Gebruik voor iTerm2, Windows Terminal of WezTerm in plaats daarvan OSC 9, en voor Kitty OSC 99. Alles buiten de toegestane sequences wordt genegeerd.

06Waar Claude Code Notifier in past

Een Notification-hook die een pushservice aanroept, krijgt de melding op je telefoon, en voor veel mensen is dat genoeg. De ntfy-handleiding laat zien hoe dat werkt.

Wat ontbreekt is antwoorden. Op het moment dat permission_prompt afgaat, wacht Claude op een dialoogvenster dat een Notification-hook niet kan beantwoorden. Claude Code Notifier lost dit op met de hooks die dat wel kunnen: PermissionRequest om je beslissing terug te geven en PreToolUse op AskUserQuestion om je antwoord terug te geven. De gratis command line tool, ccn, draait op Mac, Windows en Linux en toont zelf desktopnotificaties. Met de iPhone- of Android-app gekoppeld kun je vanaf je telefoon eenmalig toestaan, toestaan voor de sessie of weigeren. Heb je in de afgelopen 30 seconden getypt, dan wacht er niets op je telefoon en vraagt de terminal het zoals gewoonlijk. De tool is onafhankelijk en niet gemaakt door Anthropic. Installatie-instructies staan op de ccn-pagina.

07FAQ