Der Notification hook in Claude Code: wann er feuert und wie du ihn nutzt

01Die Benachrichtigungstypen

Der matcher bei einem Notification-Hook ist der Benachrichtigungstyp. Lass ihn leer, damit der Hook bei allen läuft, oder gib die gewünschten mit | getrennt an. Die Typen, die du am ehesten brauchst:

Es gibt noch weitere, etwa agent_needs_input und agent_completed für Hintergrund-Sessions in der Agent-Ansicht sowie eine Reihe von quota_auto_resume_*-Typen für Wartezeiten wegen Nutzungslimits. Die vollständige, aktuelle Liste steht in der Hooks-Referenz.

02Die Timing-Regeln

Genau hier stolpern viele. Der Notification-Hook nutzt dasselbe Timing wie die eigenen Desktop-Benachrichtigungen von Claude Code. In einer Terminal-Session feuert er also nur, wenn du wegschaust:

• permission_prompt startet einen Timer von etwa sechs Sekunden, sobald der Prompt erscheint. Jeder Tastendruck setzt ihn zurück. Antwortest du schnell, feuert er nie.
• idle_prompt feuert etwa 60 Sekunden, nachdem Claude fertig ist – aber nur, wenn du seitdem nichts getippt hast und kein Background-Agent mehr läuft. Während Claude Code auf das Zurücksetzen eines Usage-Limits wartet, feuert er nicht.
• Eine Anfrage, die eintrifft, während schon ein anderer Dialog offen ist, wird ab ihrem Eintreffen getimt. Ihre Benachrichtigung kann dich also erreichen, während sie noch hinter dem offenen Dialog wartet.

Hosts, die Berechtigungen über das Agent SDK beantworten, etwa Claude Desktop und die VS Code-Extension, timen permission_prompt anders: etwa sechs Sekunden nach der Anfrage, ohne Verzögerung durch Tippen, und übersprungen, wenn du oder ein PermissionRequest-Hook vorher antwortet.

Wenn du ein Signal ohne Verzögerung willst, nimm ein anderes Event:

03Was der Hook bekommt

Zusätzlich zu den gemeinsamen Feldern (session_id, transcript_path, cwd, hook_event_name) bekommt ein Notification-Hook die message der Benachrichtigung, optional einen title und den 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"
}

Die message ist der Originaltext von Claude Code, du kannst sie also direkt anzeigen. cwd hilft, wenn du mehrere Sessions laufen hast und wissen willst, welches Projekt gerade fragt.

04Was der Hook kann und was nicht

Ein Notification-Hook kann die Benachrichtigung weder blockieren noch verzögern oder ändern. Exit-Code und stderr werden ignoriert, und Claude Code verwirft systemMessage und continue aus seinem JSON-Output. Er ist rein für Side Effects da.

Ein Output-Feld kann er nutzen: terminalSequence. Hooks laufen ohne Terminal und können Escape-Sequenzen daher nicht selbst schreiben, aber sie können eine an Claude Code übergeben, das sie dann ausgibt. So kann ein Hook eine native Terminal-Benachrichtigung in iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal und anderen auslösen, sogar innerhalb von tmux. Das klappt nur in einer interaktiven Session, in der die Oberfläche von Claude Code auf dem Bildschirm ist.

Auch die Einstellung preferredNotifChannel hält den Hook nicht auf. Selbst mit deaktivierten eingebauten Benachrichtigungen feuert das Notification-Event weiterhin. Die Einstellung ändert nur, wie Claude Code selbst dich benachrichtigt; siehe den Guide zur Terminal-Bell.

05Beispiele

Unterschiedliche Handler pro Typ

Führ für Permission-Prompts und Idle-Erinnerungen jeweils ein eigenes Script aus:

{
  "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" }]
      }
    ]
  }
}

Mach jedes Script mit chmod +x ausführbar. Die Befehle für Desktop-Benachrichtigungen unter Mac, Windows und Linux findest du unter So bekommst du eine Benachrichtigung, wenn Claude Code fertig ist, deshalb wiederholen wir sie hier nicht.

Die echte Nachricht und das Projekt anzeigen

Dieses Script (macOS und Linux) packt die Nachricht von Claude Code und den Projektordner in die Benachrichtigung statt eines festen Strings:

#!/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

Wenn du den Text als Argumente übergibst (on run argv), bricht das AppleScript nicht, falls die Nachricht Anführungszeichen enthält. jq muss installiert sein.

Eine native Terminal-Benachrichtigung

Das Beispiel von Anthropic selbst nutzt terminalSequence mit OSC 777, das Ghostty, Warp und urxvt verstehen:

#!/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}'

Für iTerm2, Windows Terminal oder WezTerm nimmst du stattdessen OSC 9, für Kitty OSC 99. Alles außerhalb der erlaubten Sequenzen wird ignoriert.

06Wo Claude Code Notifier ins Spiel kommt

Ein Notification-Hook, der einen Push-Dienst aufruft, bringt den Alert auf dein Handy – und vielen reicht das. Der ntfy-Guide zeigt diesen Weg.

Was fehlt, ist die Antwort. Wenn permission_prompt feuert, wartet Claude auf einen Dialog, den ein Notification-Hook nicht beantworten kann. Claude Code Notifier löst das mit den Hooks, die es können: PermissionRequest, um deine Entscheidung zurückzugeben, und PreToolUse auf AskUserQuestion, um deine Antwort zurückzugeben. Das kostenlose Kommandozeilen-Tool ccn läuft auf Mac, Windows und Linux und zeigt auch allein Desktop-Benachrichtigungen an. Mit gekoppelter iPhone- oder Android-App kannst du vom Handy aus einmal erlauben, für die Session erlauben oder ablehnen. Hast du in den letzten 30 Sekunden getippt, wartet nichts aufs Handy und das Terminal fragt wie gewohnt. Das Tool ist unabhängig und nicht von Anthropic. Die Installation findest du auf der ccn-Seite.

07FAQ