Guida
Gli hook di Claude Code, spiegati: cosa sono e cosa puoi costruire
In breve: Gli hook permettono a Claude Code di eseguire un tuo comando quando parte uno strumento, quando chiede un permesso o quando finisce un turno. Come funzionano e come li usa Herdbell.
Un hook è un piccolo comando che un agente esegue in un momento preciso. Claude Code, Codex e Cursor li supportano tutti in qualche forma, e sono il modo pulito per permettere a un altro programma di seguire ciò che fa un agente, senza accedere a nulla né leggere lo schermo.
L’idea in un paragrafo
Dici all’agente: quando succede questo, esegui questo comando. L’agente lo esegue e gli passa una breve descrizione dell’evento. Il comando può limitarsi a registrarlo (per esempio per inviare una notifica) oppure, per alcuni eventi, può restituire una risposta che l’agente usa.
Momenti a cui puoi agganciarti
I nomi esatti degli eventi e le impostazioni cambiano da un agente e da una versione all’altra, quindi consulta la documentazione di ogni agente prima di scrivere il tuo.
- Una sessione inizia o finisce, oppure invii un prompt.
- Uno strumento sta per essere eseguito, o è appena stato eseguito.
- L’agente chiede il permesso di fare qualcosa.
- L’agente finisce il suo turno (un evento Stop).
Dove vivono
In un file di impostazioni: per Claude Code è ~/.claude/settings.json, per Codex ~/.codex/hooks.json e per Cursor ~/.cursor/hooks.json. Modificare questi file a mano va benissimo ed è anche il modo in cui si collega uno strumento come Herdbell.
Come li usa Herdbell
- Al momento del collegamento, Herdbell fa un backup del file, poi aggiunge il proprio piccolo comando per gli eventi che gli servono.
- Per la maggior parte degli eventi si limita ad ascoltare, così può mostrare cosa sta facendo l’agente.
- Per una richiesta di permesso attende la tua risposta e la restituisce, così Allow e Deny hanno effetto. Per la fine del turno può tenere l’agente in attesa così la tua risposta torna nella stessa chat.
- Se non rispondi in tempo, lascia andare e l’agente torna alla propria richiesta. Scollegare rimuove solo gli hook di Herdbell.
Domande frequenti
Gli hook richiedono una chiave API o un accesso?
No. Un hook è un comando locale sul tuo Mac. Herdbell li usa così non ha mai bisogno di accedere a un agente né di chiamare un modello di IA.
Un hook può rompere il mio agente?
Uno scritto male può rallentarlo o confonderlo, ed è per questo che Herdbell fa prima un backup delle tue impostazioni, mantiene i suoi hook piccoli e lascia andare quando non rispondi. Puoi scollegarlo in qualsiasi momento.