Le notifiche di Claude Code non funzionano? Una checklist

011. Verifica che Claude Code abbia caricato l'hook

Digita /hooks nel prompt di Claude Code. È un browser in sola lettura di tutti gli hook caricati da Claude Code, e per ognuno indica la provenienza: impostazioni utente, di progetto, locali, un plugin o la sessione corrente. Seleziona un hook per vedere il comando esatto e il file in cui è definito.

Se il tuo hook non è nella lista:

• Il JSON non è valido. I file di impostazioni sono JSON rigoroso. Una virgola finale o un commento // rompono il file, e Claude Code segnala un Settings Error all'avvio successivo. Esegui claude doctor per vedere le voci che Claude Code ha rifiutato.
• Il file è nel posto sbagliato. Gli hook personali vanno in ~/.claude/settings.json (su Windows, %USERPROFILE%\.claude\settings.json). Gli hook di progetto vanno in .claude/settings.json dentro il progetto. Esegui /status e leggi la riga Setting sources per vedere quali file sono stati caricati.
• Il nome dell'evento è sbagliato. I nomi degli eventi distinguono maiuscole e minuscole: Notification, Stop, PermissionRequest. Un nome di evento sconosciuto compare come Settings Warning e viene ignorato.
• Gli hook sono disattivati. "disableAllHooks": true in un qualsiasi file di impostazioni disattiva tutti gli hook. Se /hooks mostra Only hooks from managed settings run here, la tua organizzazione ha impostato allowManagedHooksOnly e i tuoi hook non verranno eseguiti.
• La modifica non è stata rilevata. Di solito Claude Code ricarica le impostazioni da solo. Se l'hook non compare dopo qualche secondo, riavvia la sessione.

022. Accetta la fiducia nel workspace

In una sessione interattiva, Claude Code blocca gli hook di tutti i file di impostazioni, compreso il tuo ~/.claude/settings.json, finché non accetti la finestra di fiducia del workspace per quella cartella. Se hai chiuso quella finestra, o sei in una cartella in cui non hai mai aperto Claude Code, lì i tuoi hook non girano. Avvia claude in quella cartella e accetta.

033. Assicurati che l'evento parta quando pensi

Molte notifiche "rotte" sono in realtà una questione di tempistica. Dal riferimento sugli hook di Anthropic:

Quindi se provi un hook Notification mentre scrivi nel terminale, potrebbe non partire mai. Passa a un'altra finestra e aspetta. Per un avviso immediato alla fine di un turno, usa Stop; trovi tutto nella guida allo Stop hook.

Controlla anche la modalità dei permessi. Le versioni recenti di Claude Code avviano le sessioni interattive in modalità auto, dove un classificatore approva la maggior parte delle azioni senza chiedere. Nessuna richiesta significa nessuna notifica permission_prompt e nessun hook PermissionRequest. Per testare gli avvisi sui permessi, premi Shift+Tab finché la barra di stato non mostra la modalità manuale, poi chiedi a Claude di fare qualcosa che richiede approvazione. Trovi i dettagli in Le modalità dei permessi spiegate.

Anche i matcher distinguono maiuscole e minuscole. Un matcher PermissionRequest con bash non corrisponde al tool Bash.

044. Esegui tu stesso il comando dell'hook

Copia il comando da /hooks ed eseguilo in un terminale con un input di esempio:

echo '{"hook_event_name":"Stop","cwd":"/tmp","last_assistant_message":"done"}' | ./my-hook.sh
echo $?

Errori comuni:

• command not found: usa un percorso assoluto per lo script, oppure ${CLAUDE_PROJECT_DIR} per gli script nel progetto.
• Lo script non fa assolutamente nulla: rendilo eseguibile con chmod +x ./my-hook.sh.
• jq: command not found: installa jq, oppure fai il parsing del JSON con Python o Node.js.

055. Leggi il log di debug

Avvia Claude Code con claude --debug. Nel terminale non compare nulla in più; il log finisce in ~/.claude/debug/<session-id>.txt. Per scegliere il percorso, usa claude --debug-file /tmp/claude.log ed esegui tail -f /tmp/claude.log in un altro terminale. Se la sessione è già avviata, /debug attiva il logging e ti dice dove si trova il log.

Cerca le righe che iniziano con Hooks:. Ognuna indica l'evento, il comando, come è terminato (finished with status 0, timed out, failed to start) e quanto ci ha messo. Per più dettagli sul matching, imposta CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Due problemi emergono solo qui:

• Il profilo della shell stampa qualcosa. Se ~/.bashrc o ~/.zshrc esegue un echo e la shell lo carica, quel testo finisce davanti all'output JSON del tuo hook, e Claude Code tratta l'output come testo semplice. Cerca nel log Hook output does not start with {. Racchiudi l'output del profilo in if [[ $- == *i* ]]; then ... fi così viene eseguito solo nelle shell interattive.
• Nessun terminale su cui scrivere. Su Mac e Linux, gli hook di tipo command girano senza un terminale di controllo. Un hook che prova a suonare il bell o a scrivere escape code su /dev/tty fallisce senza dire nulla. Usa invece un comando di notifica desktop, oppure l'impostazione preferredNotifChannel di Claude Code, descritta nella guida al terminal bell.

066. Controlla il sistema operativo

Se il log di debug dice che l'hook è terminato con status 0 e comunque non hai visto nulla, è stato il sistema operativo a nasconderla. Controlla che l'app che mostra l'avviso abbia il permesso di inviare notifiche e che Full immersion (Mac), Non disturbare (Windows) o l'opzione non disturbare del tuo desktop Linux siano disattivati. Su Linux deve essere in esecuzione un demone di notifica.

Trovi i comandi specifici per piattaforma nelle guide per macOS, Windows e Linux.

07Se usi Claude Code Notifier

Claude Code Notifier è uno strumento indipendente (non realizzato da Anthropic) che installa un piccolo programma, ccn, come hook di Claude Code. Tutto quanto detto sopra vale ancora, perché ccn è un hook come gli altri. Parti dai suoi controlli:

1. ccn doctor controlla gli hook, le credenziali, la connessione al server e il rilevamento della presenza. Risolvi prima qualsiasi problema segnali.
2. ccn test invia una notifica di prova. Se arriva, il problema è l'evento o un'impostazione, non la pipeline.
3. ccn devices elenca i telefoni associati a questo computer. Se non ce n'è nessuno, ripeti l'associazione con ccn pair; la guida all'associazione ti accompagna passo passo.
4. ccn config show mostra le impostazioni effettive. Verifica che notify_on_done, notify_on_permission e notify_on_question siano attivi e che quiet_hours non copra l'orario attuale. Le impostazioni modificate sul telefono arrivano al computer con ccn sync.

Alcuni comportamenti sembrano guasti, ma sono voluti:

• Sei alla tastiera. Se hai digitato negli ultimi 30 secondi, non si aspetta il telefono e il terminal chiede come al solito. Con quiet_when_present attivo (il default), il telefono non riceve nulla mentre sei nel terminal in cui gira Claude, e riceve una scheda informativa se sei attivo in un'altra app.
• Avvisi duplicati o mancanti su Mac. Non usare la vecchia app per la barra dei menu del Mac insieme a ccn sullo stesso Mac.
• Una lunga pausa. Se un telefono o un computer non viene usato per 60 giorni, il server ne elimina l'associazione e devi ripeterla.

Sul telefono, controlla che le notifiche siano consentite per l'app e che Full immersion (iPhone) o Non disturbare (Android) non le silenzino. Su Android l'ottimizzazione della batteria può ritardare le notifiche di alcune app; se gli avvisi arrivano in ritardo, consenti all'app di funzionare senza restrizioni nelle impostazioni della batteria. Se hai modificato settings.json a mano, ccn doctor ti dice se i suoi hook sono ancora al loro posto. ccn upgrade aggiorna all'ultima release.

08FAQ