Il Notification hook di Claude Code: quando scatta e come usarlo

01I tipi di notifica

Il matcher di un hook Notification è il tipo di notifica. Lascialo vuoto per eseguirlo su tutti, oppure elenca quelli che ti interessano separandoli con |. I tipi che userai più spesso:

Ce ne sono altri, come agent_needs_input e agent_completed per le sessioni in background nella vista agent, e una serie di tipi quota_auto_resume_* per le attese dovute ai limiti di utilizzo. Il riferimento sugli hook ha l'elenco completo e aggiornato.

02Le regole sulle tempistiche

Questo è il punto su cui molti si confondono. Il hook Notification ha le stesse tempistiche delle notifiche desktop di Claude Code, quindi in una sessione da terminale scatta solo quando distogli lo sguardo:

• permission_prompt avvia un timer di circa sei secondi quando compare il prompt. Ogni tasto premuto lo azzera. Se rispondi in fretta, non scatta mai.
• idle_prompt scatta circa 60 secondi dopo che Claude ha finito, solo se nel frattempo non hai digitato nulla e non c'è ancora un agent in background in esecuzione. Non scatta mentre Claude Code aspetta il reset di un limite di utilizzo.
• Una richiesta che arriva mentre è aperto un altro dialog viene cronometrata dal momento in cui arriva, quindi la sua notifica può raggiungerti mentre è ancora in coda dietro al dialog aperto.

Gli host che gestiscono i permessi tramite l'Agent SDK, come Claude Desktop e l'estensione per VS Code, gestiscono i tempi di permission_prompt in modo diverso: circa sei secondi dopo la richiesta, senza rinvii dovuti alla digitazione, e saltato se tu o un hook PermissionRequest rispondete prima.

Se vuoi un segnale senza ritardo, usa un altro evento:

03Cosa riceve il hook

Oltre ai campi comuni (session_id, transcript_path, cwd, hook_event_name), un hook Notification riceve il message della notifica, un title opzionale e il 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"
}

Il message è il testo originale di Claude Code, quindi puoi mostrarlo così com'è. cwd è utile quando hai più sessioni aperte e vuoi sapere quale progetto ti sta chiamando.

04Cosa può e non può fare il hook

Un hook Notification non può bloccare, ritardare o modificare la notifica. Exit code e stderr vengono ignorati, e Claude Code scarta systemMessage e continue dal suo output JSON. Serve solo per gli effetti collaterali.

C'è un solo campo di output che può usare: terminalSequence. Gli hook girano senza terminale, quindi non possono scrivere direttamente sequenze di escape, ma possono passarne una a Claude Code perché la emetta. Così un hook può attivare una notifica nativa del terminale in iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal e altri, anche dentro tmux. Funziona solo in una sessione interattiva con l'interfaccia di Claude Code a schermo.

Nemmeno l'impostazione preferredNotifChannel ferma il hook. Anche con le notifiche integrate disattivate, l'evento Notification scatta comunque. Quell'impostazione cambia solo il modo in cui Claude Code ti avvisa; vedi la guida sulla campanella del terminale.

05Esempi

Handler diversi per tipo

Esegui uno script separato per i prompt di permesso e per i promemoria di inattività:

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

Rendi eseguibile ogni script con chmod +x. I comandi per le notifiche desktop su Mac, Windows e Linux sono in come ricevere una notifica quando Claude Code finisce, quindi non li ripetiamo qui.

Mostra il messaggio reale e il progetto

Questo script (macOS e Linux) mette nella notifica il messaggio di Claude Code e la cartella del progetto, invece di una stringa fissa:

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

Passare il testo come argomenti (on run argv) evita di rompere l'AppleScript quando il messaggio contiene virgolette. Richiede jq installato.

Una notifica nativa del terminale

L'esempio ufficiale di Anthropic usa terminalSequence con OSC 777, supportato da Ghostty, Warp e urxvt:

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

Per iTerm2, Windows Terminal o WezTerm usa invece OSC 9, e per Kitty OSC 99. Tutto ciò che non rientra nelle sequenze consentite viene ignorato.

06Dove si inserisce Claude Code Notifier

Un hook Notification che chiama un servizio push ti porta l'avviso sul telefono, e per molti basta così. La guida a ntfy mostra come fare.

Quello che manca è la risposta. Quando scatta permission_prompt, Claude è fermo su un dialog a cui un hook Notification non può rispondere. Claude Code Notifier risolve usando gli hook che possono farlo: PermissionRequest per restituire la tua decisione e PreToolUse su AskUserQuestion per restituire la tua risposta. Il suo tool da riga di comando gratuito, ccn, gira su Mac, Windows e Linux e mostra notifiche desktop anche da solo. Con l'app per iPhone o Android abbinata, puoi consentire una volta, consentire per la sessione o negare dal telefono. Se hai digitato negli ultimi 30 secondi, non si aspetta il telefono e il terminale chiede come al solito. È un progetto indipendente, non realizzato da Anthropic. Le istruzioni di installazione sono nella pagina di ccn.

07FAQ