Workbranch › Guide

Come usare gli hook in Claude Code

Vuoi che qualcosa succeda ogni volta, come formattare un file dopo che Claude lo ha modificato o ricevere un avviso quando Claude ti sta aspettando, senza sperare che Claude se ne ricordi. Gli hook fanno esattamente questo. Questa guida spiega cosa sono, ti accompagna nella creazione di un primo hook e mostra dove metterli.

Aggiornato 30 ottobre 2026

Nomi degli eventi, posizioni dei file e comportamento descritti qui sotto provengono dalla documentazione di Claude Code di Anthropic a ottobre 2026. Claude Code si aggiorna spesso, quindi esegui claude update se manca qualcosa.

Cosa sono gli hook e perché aiutano

Le istruzioni in un prompt o in un file CLAUDE.md sono suggerimenti: Claude di solito le segue, ma decide lui. Un hook è diverso. È Claude Code stesso a eseguire il tuo comando ogni volta che si verifica l'evento, quindi l'azione è deterministica. Usi tipici dalla guida di Anthropic:

• Notifiche quando Claude aspetta un permesso o una tua risposta.
• Formattazione automatica di ogni file dopo che Claude lo modifica o lo scrive.
• Blocco delle modifiche a file sensibili come .env o a qualsiasi cosa in .git/.
• Aggiunta di contesto, per esempio ricordare a Claude le convenzioni del progetto dopo che la conversazione è stata compattata.

Tra gli eventi più usati ci sono SessionStart (una sessione inizia o riprende), UserPromptSubmit (invii un prompt), PreToolUse (prima di una chiamata a uno strumento, e può bloccarla), PostToolUse (dopo che una chiamata a uno strumento è riuscita), Notification, Stop (Claude finisce di rispondere), PreCompact e SessionEnd. L'elenco completo nella documentazione di riferimento degli hook è molto più lungo.

Configura il tuo primo hook: una notifica sul desktop

Questo esempio, adattato dalla guida passo passo di Anthropic, ti avvisa su macOS ogni volta che Claude Code ha bisogno della tua attenzione.

1. Apri ~/.claude/settings.json in un editor di testo. Crea il file se non esiste.
2. Aggiungi un oggetto hooks con una voce Notification. Al suo interno va un elenco di gruppi matcher; ognuno ha un matcher (lascialo come stringa vuota per attivarlo a ogni notifica) e un elenco hooks con un elemento di "type": "command".
3. Imposta il comando su osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. Su Linux, l'esempio di Anthropic usa invece notify-send. Ricordati di fare l'escape delle virgolette doppie interne nel JSON.
4. Se il file ha già una chiave hooks, aggiungi Notification accanto agli eventi esistenti invece di sostituire l'intero oggetto.
5. In Claude Code, digita /hooks. Il browser degli hook dovrebbe mostrare il nuovo hook sotto Notification. Premi Esc per tornare indietro.
6. Chiedi a Claude qualcosa che richiede un permesso e passa a un'altra finestra. Dovrebbe comparire una notifica.

Un secondo esempio: formattare i file dopo le modifiche

Per un hook di progetto, metti la configurazione in .claude/settings.json nella radice del progetto. Usa l'evento PostToolUse con il matcher Edit|Write, così viene eseguito solo dopo gli strumenti che modificano i file. Il comando di esempio di Anthropic legge il percorso modificato dal JSON che Claude Code passa sullo standard input e lo passa a Prettier: jq -r '.tool_input.file_path' | xargs npx prettier --write. Richiede che jq sia installato. Un hook riuscito non mostra nulla nella conversazione; vedrai semplicemente il file riformattato.

Dove si configurano gli hook

Per disattivare gli hook, imposta "disableAllHooks": true in un file di impostazioni. Gli hook delle impostazioni gestite continuano a funzionare, a meno che non sia impostato anche lì.

Come risponde un hook

Quando si verifica un evento, Claude Code invia i dettagli dell'evento in JSON allo standard input del tuo comando. Il comando risponde con il suo exit code:

• Exit 0: si procede. Per alcuni eventi, come SessionStart, il testo semplice stampato sullo standard output viene aggiunto al contesto di Claude.
• Exit 2: blocca l'azione, dove l'evento lo consente. Scrivi il motivo sullo standard error; per PreToolUse, Claude lo riceve e può cambiare strada.
• Altri codici: di solito trattati come errore non bloccante; l'azione procede e la trascrizione mostra un errore dell'hook.

Per un controllo più preciso, esci con 0 e stampa invece un oggetto JSON. Scegli un solo approccio per ogni hook.

Da sapere

• Gli hook di tipo command non possono eseguire comandi slash né chiamare strumenti da soli.
• Il timeout predefinito degli hook di tipo command è di 10 minuti, più breve per alcuni eventi; imposta timeout (in secondi) su ogni hook per cambiarlo.
• PostToolUse non può annullare nulla, perché lo strumento è già stato eseguito. Usa PreToolUse per impedire un'azione.
• Stop si attiva ogni volta che Claude finisce una risposta, non solo quando un compito è completato.

Se non funziona

• L'hook non si attiva mai: esegui /hooks e controlla che sia elencato sotto l'evento giusto. I matcher distinguono maiuscole e minuscole e devono corrispondere esattamente al nome dello strumento, per esempio Edit, non edit.
• "/hooks" non mostra nulla: controlla che il JSON sia valido (niente virgole finali né commenti) e che sia nel file giusto. Di solito le modifiche vengono recepite automaticamente; altrimenti riavvia la sessione.
• "hook error" nella trascrizione: prova lo script passandogli un JSON di esempio tramite pipe e controlla echo $?. Usa percorsi assoluti o $CLAUDE_PROJECT_DIR per gli script, installa jq se manca e rendi eseguibili gli script con chmod +x.
• Nessuna notifica su macOS: esegui una volta il comando osascript nel Terminale, poi attiva Allow Notifications (consenti notifiche) per Script Editor in System Settings > Notifications (Impostazioni di Sistema > Notifiche).

Tieni traccia di ciò che ogni sessione lascia in sospeso

Il plugin Workbranch per Claude Code usa un riepilogo all'avvio della sessione: in una cartella collegata a un progetto Workbranch, mostra cosa è ancora aperto quando inizia una sessione, e se dici "save this to Workbranch" (salva questo su Workbranch) archivia in quel progetto i compiti, le decisioni e le domande aperte della sessione. Vedi Workbranch per Claude. Sei alle prime armi con Claude Code? Parti da come iniziare con Claude Code.

Fonti

• Use Claude Code with your Pro or Max plan (Claude Help Center, verificato il 30 ottobre 2026)
• Automate actions with hooks (Claude Code docs, verificato il 30 ottobre 2026)

Domande frequenti