Personalizzazione di Claude Code per utenti esperti: come configurare gli hook

Anche un flusso di lavoro fluido di Claude Code accumula punti di attrito nel tempo. Ogni volta che Claude scrive un file, Prettier deve essere eseguito manualmente. Ogni volta che viene eseguito npm test, viene visualizzato lo stesso prompt dei permessi. Ogni sessione inizia con l'incollare lo stesso contesto di progetto standard nel primo messaggio.

La buona notizia? Gli hook eliminano questi punti di attrito. Funzionano come trigger che puoi configurare per essere attivati prima o dopo determinate azioni, consentendoti di iniettare logica personalizzata, script e comandi direttamente nelle operazioni di Claude.

Questo articolo illustra la configurazione avanzata per gli sviluppatori che hanno già familiarità con le basi di Claude Code. Alla fine di questo articolo avrai compreso gli otto tipi di hook, quando utilizzare ciascuno, come configurarli e come eseguire il debug in caso di problemi.

Iniziamo.

Cos'è un hook?

Un hook è un comando di shell personalizzato che crei per l'esecuzione automatica quando si verifica un evento mirato nella sessione di Claude Code, ad esempio quando Claude sta per scrivere un file o quando invii un prompt. Puoi configurare gli hook per un'ampia gamma di attività: intercettare azioni prima che vengano eseguite, inserire il contesto dell'agente, automatizzare le approvazioni o bloccare le operazioni prima che vengano eseguite.

Gli hook vengono configurati nei file delle impostazioni utilizzando una struttura JSON con nomi di eventi, matcher (per filtrare quali strumenti attivano l'hook) e i comandi da eseguire. Si eseguono nel tuo ambiente locale con le tue autorizzazioni utente, ricevono informazioni sull'evento attivante tramite stdin e comunicano tramite codici di uscita e stdout. In questo modo, hai un controllo preciso sul comportamento di Claude Code senza modificare lo strumento stesso.

Perché utilizzare gli hook in Claude Code?

Gli hook risolvono tre categorie di problemi.

Innanzitutto, eliminano i passaggi manuali ripetitivi. Anziché eseguire il formattatore dopo ogni modifica al file, un hook PostToolUse lo gestisce automaticamente. Invece di approvare npm test per la centesima volta, un hook PermissionRequest lo approva automaticamente.

In secondo luogo, gli hook applicano automaticamente le regole specifiche del progetto. Puoi bloccare comandi pericolosi prima che vengano eseguiti, convalidare i percorsi dei file prima della scrittura o garantire il rispetto delle convenzioni di denominazione. Queste salvaguardie vengono eseguite ogni volta, non solo quando ricordi di effettuare il controllo.

In terzo luogo, gli hook iniettano il contesto dinamico senza sforzo manuale. Un hook SessionStart può fornire a Claude lo Stato del servizio git corrente e l'elenco TODO. Un hook UserPromptSubmit può aggiungere le priorità dei sprint a ogni richiesta. Claude rimane informato senza che tu debba ripeterti.

Tipi di hook Claude Code e quando utilizzarli

Claude Code fornisce otto eventi hook che coprono l'intero ciclo di vita di una sessione, dall'avvio all'esecuzione degli strumenti fino al completamento. Ciascuno viene attivato in un momento specifico, consentendoti di controllare con precisione quando viene eseguita l'automazione. Scegliere l'hook giusto dipende da ciò che vuoi ottenere.

Hook a colpo d'occhio

PreToolUse

Questo è l'hook più comunemente utilizzato, che viene attivato dopo che Claude ha scelto uno strumento da utilizzare, ma prima che lo strumento venga effettivamente eseguito. Lo script può ispezionare l'azione pianificata e approvarla, bloccarla, richiedere conferma all'utente o modificare i parametri, utilizzando un matcher per filtrare quali strumenti attivano questo hook.

Questo esempio di hook PreToolUse valuta le scritture di file prima della loro esecuzione. Claude esamina l'azione pianificata rispetto ai criteri specificati e può approvare, bloccare o segnalare preoccupazioni in base alla logica del prompt.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-file-path.sh"
          }
        ]
      }
    ]
  }
}

Quando utilizzare PreToolUse:

• Blocco di comandi Bash pericolosi come rm -rf o force push
• Approvazione automatica di operazioni sicure e ripetitive per ridurre l'affaticamento da prompt
• Convalida dei percorsi dei file prima delle scritture per evitare sovrascritture accidentali
• Modifica degli input degli strumenti per inserire valori predefiniti specifici del progetto

PermissionRequest

Questo hook si attiva quando Claude normalmente visualizzerebbe una finestra di dialogo delle autorizzazioni. Questo hook intercetta il momento prima che tu visualizzi un prompt di conferma, lasciando al tuo script la decisione se consentire, rifiutare o comunque chiedere all'utente.

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash(npm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-test-command.sh"
          }
        ]
      }
    ]
  }
}

Questo esempio approva automaticamente qualsiasi comando Bash che inizia con npm test. Il pattern del matcher può includere argomenti per un controllo più preciso.

Quando utilizzare PermissionRequest:

• Approvazione automatica dei comandi di test che vengono eseguiti decine di volte per sessione
• Blocco dell'accesso in scrittura ai file di configurazione di produzione
• Consentire operazioni di lettura su directory specifiche senza prompt
• Rifiutare qualsiasi comando che corrisponde a un pattern pericoloso

PostToolUse

Si attiva immediatamente dopo il completamento positivo dello strumento. Lo script riceve informazioni su cosa è successo, incluso l'output degli strumenti, utilizzando i matcher per filtrare quali strumenti lo attivano.

Questo esempio di PostToolUse esegue Prettier su qualsiasi file scritto o modificato da Claude. La sintassi della pipe nel matcher significa che viene attivata sia per gli strumenti Write che Edit.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Quando utilizzare PostToolUse:

• Esecuzione di Prettier, Black o gofmt dopo ogni scrittura di file per imporre la formattazione
• Registrazione di tutte le modifiche ai file in un audit trail
• Attivazione di linters e visualizzazione di avvisi dopo le modifiche al codice
• Invio di notifiche al completamento di determinate operazioni

PreCompact

Si attiva prima che Claude compatti il contesto della conversazione per liberare spazio. La compattazione riassume le parti più vecchie della conversazione, il che significa che alcuni dettagli vengono persi. Questo hook offre la possibilità di conservare le informazioni prima che ciò accada.

Questo esempio di PreCompact esegue il backup della trascrizione prima della compattazione automatica. Il matcher può essere "automatico" o "manuale", così da poter distinguere tra compattazione automatica ed eventi di compattazione attivati dall'utente.

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/backup-transcript.sh"
          }
        ]
      }
    ]
  }
}

Quando utilizzare PreCompact:

• Eseguire il backup dell'intera trascrizione in un file prima del riepilogo
• Estrarre e salvare decisioni importanti o frammenti di codice
• Registrare le tappe fondamentali delle sessioni per la revisione successiva

SessionStart

Si attiva quando Claude Code avvia una nuova sessione o riprende una sessione esistente. Tutto ciò che lo script produce viene aggiunto al contesto della conversazione, quindi Claude inizia con quelle informazioni già caricate.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git status --short && echo '---' && cat TODO.md"
          }
        ]
      }
    ]
  }
}

Ogni sessione inizia con Claude che conosce lo stato del servizio git corrente e l'elenco TODO. Stdout diventa automaticamente contesto.

Quando utilizzare SessionStart:

• Invio a Claude del branch git corrente e dei commit recenti
• Caricamento dei contenuti dell'elenco TODO o del backlog dello sprint
• Inserimento di dettagli di configurazione specifici dell'ambiente

Stop

Si attiva quando Claude finisce di rispondere e normalmente attenderebbe il tuo input successivo. Il tuo script può ispezionare ciò che Claude ha prodotto e decidere se l'attività è veramente completa.

Lo script può restituire JSON con "continue": true per far continuare il lavoro di Claude, il che è utile per i flussi di lavoro in più passaggi:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review whether the task is complete. If all requirements are met, respond with 'complete'. If work remains, respond with 'continue' and specify what still needs to be done."
          }
        ]
      }
    ]
  }
}

Quando utilizzare Stop:

• Costringere Claude a continuare fino a quando tutte le voci di un elenco di controllo sono completate
• Verificare che i test passino prima di considerare completata un'attività
• Attivazione della generazione di riepilogo al termine di una sessione
• Verifica che il codice generato venga compilato correttamente prima di interrompere

SubagentStop

Questo hook si attiva ogni volta che un subagente creato tramite lo strumento Attività termina. Funziona allo stesso modo di Stop, ma si attiva specificamente quando un subagent completa la propria azione (anziché l'agente principale). La configurazione di SubagentStop rispecchia la struttura degli hook Stop:

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate the subagent's output. Verify the task was completed correctly and the results meet quality standards. If the output is satisfactory, respond with 'accept'. If issues exist, respond with 'reject' and explain what needs to be fixed."
          }
        ]
      }
          ]
  }
}

Quando utilizzare SubagentStop:

• Convalida che l'output del subagente soddisfi i criteri di qualità
• Attivazione di azioni di follow-up in base ai risultati dei subagenti
• Registrazione delle attività dei subagenti per scopi di debug o di controllo

UserPromptSubmit

Si attiva quando invii un prompt, prima che Claude lo elabori. Qualsiasi output dello script tramite stdout viene aggiunto al contesto di Claude insieme al prompt. Ciò rende UserPromptSubmit utile per inserire dinamicamente informazioni che Claude dovrebbe prendere in considerazione.

In questo esempio, ogni volta che invii un prompt, Claude riceve i contenuti del file di contesto del tuo sprint. In questo modo, Claude resta al corrente delle priorità attuali senza che tu debba riformularle.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ./current-sprint-context.md"
          }
        ]
      }
    ]
  }
}

Quando utilizzare UserPromptSubmit:

• Inserimento del contesto dello sprint corrente o delle priorità del progetto con ogni prompt
• Convalida dei prompt prima che raggiungano Claude
• Blocco di determinati tipi di richieste in base al contenuto
• Aggiunta di contesto dinamico, come log degli errori recenti o risultati dei test

Configurazione e posizioni dei file

Gli hook risiedono nei file delle impostazioni JSON a tre livelli. Gli hook a livello di progetto vengono memorizzati in .claude/settings.json all'interno del tuo repository, così da poterli condividere con il tuo team. Gli hook a livello utente vengono memorizzati in ~/.claude/settings.json e si applicano a tutti i tuoi progetti. Gli hook di progetto locali vengono memorizzati in .claude/settings.local.json per una configurazione personale che non desideri includere nel commit.

Le impostazioni a livello di progetto hanno la precedenza su quelle a livello di utente. Sono inoltre disponibili impostazioni dei criteri gestiti dall'azienda che possono essere controllate dall'organizzazione. Per dettagli completi, consultare le informazioni sulle impostazioni di Claude Code.

Suggerimento avanzato: questo è lo stesso file in cui è possibile impostare autorizzazioni granulari per le azioni di Claude, a livello di progetto, utente o locale. Ad esempio, è possibile consentire esplicitamente a Claude la lettura di tutti i file in una directory, senza dover approvare l'operazione ogni volta, oppure bloccare qualsiasi modifica ai file riservati.

Sintassi del matcher

I matcher consentono di filtrare gli strumenti che possono attivare il proprio hook. Si applicano esclusivamente agli hook PreToolUse, PostToolUse e PermissionRequest.

La semplice corrispondenza delle stringhe funziona esattamente come ci si aspetterebbe: "Write" corrisponde solo allo strumento Write (Scrittura).

Ad esempio:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

La sintassi delle pipe consente di associare più strumenti: "Write|Edit" si attiva per entrambi, mentre i wildcard corrispondono a tutto: "*" o una stringa vuota corrisponde a tutti gli strumenti.

Nota: i matcher fanno distinzione tra maiuscole e minuscole, pertanto "bash" non verrà abbinato allo strumento Bash.

Per un controllo più preciso, i modelli di argomento come "Bash(npm test*)" possono corrispondere ad argomenti di comando specifici. I modelli per gli strumenti MCP seguono il formato "mcp__memory__.*" per gli strumenti Model Context Protocol.

Input, output e risposte strutturate

Cosa ricevono gli hook

Tutti gli hook ricevono JSON tramite stdin contenente informazioni sulla sessione e dati specifici per eventi. I campi comuni includono: session_id, transcript_path, cwd, permission_mode e hook_event_name.

Inoltre, gli hook correlati agli strumenti ricevono anche tool_name e tool_input. Questi dati consentono agli script di prendere decisioni informate su come rispondere.

Come rispondono gli hook

I codici di uscita determinano il risultato di base. Exit code 0 indica l'esito positivo e stdout viene elaborato per JSON o aggiunto al contesto. Exit code 2 significa un errore di blocco: stderr diventa il messaggio di errore e l'azione viene impedita.

Altri codici di uscita indicano errori non di blocco, con stderr visualizzato in modalità verbosa.

Oltre ai codici di uscita, gli hook possono restituire JSON strutturato per un maggiore controllo. I campi includono: decision (approve, block, allow o deny), reason (spiegazione mostrata a Claude), continue (per gli hook Stop per forzare il proseguimento) e updatedInput (per modificare i parametri dello strumento prima dell'esecuzione).

Ambiente ed esecuzione

Gli hook hanno accesso alle variabili d'ambiente, tra cui: CLAUDE_PROJECT_DIR per il percorso radice del progetto, CLAUDE_CODE_REMOTE che è true per gli ambienti web e CLAUDE_ENV_FILE per gli hook SessionStart per mantenere le variabili. Sono inoltre accessibili le variabili d'ambiente standard dalla shell.

Da segnalare inoltre: gli hook hanno un timeout predefinito di 60 secondi, configurabile per hook. Quando più hook corrispondono a un evento, vengono eseguiti in parallelo. I comandi identici vengono deduplicati automaticamente.

Considerazioni sulla sicurezza

Gli hook eseguono comandi di shell arbitrari utilizzando le tue autorizzazioni utente. Claude Code include una salvaguardia: le modifiche dirette ai file di configurazione degli hook devono essere esaminate nel menu /hooks prima di avere effetto. Questo impedisce al codice dannoso di aggiungere silenziosamente hook alla configurazione.

Tuttavia, se configuri e approvi gli hook, questi verranno eseguiti ai suoi livelli di autorizzazione.

Suggerimento: prima di eseguire comandi in un ambiente, considera i rischi. Se hai intenzione di eseguire comandi con hook, prendi in considerazione best practice quali: convalida e pulizia degli input da stdin, uso delle virgolette per le variabili di shell per prevenire l'injection, utilizzo di percorsi assoluti per gli script ed evitare l'elaborazione di file riservati come .env o credenziali.

Debug e test

Claude Code registra tutto nei file di trascrizione, fornendo visibilità sulle chiamate e sulle risposte degli strumenti senza alcuna configurazione. Ogni hook riceve un campo transcript_path che punta a un file JSONL contenente la cronologia completa della sessione. È possibile utilizzare un hook SessionStart per registrare dove si trova ogni trascrizione:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"Session: \" + .transcript_path' >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

Quindi monitora la trascrizione con tail per osservare Claude mentre lavora in tempo reale: tail -f /path/to/transcript.jsonl | jq.

Debug specifico per gli hook

Per il debug specifico degli hook, aggiungi il logging ai tuoi script di hook. I file di trascrizione mostrano cosa ha fatto Claude, ma non perché il tuo hook ha intrapreso l'azione per approvare o bloccare qualcosa.

Con un piccolo sforzo in più, puoi aggiungere un piccolo script bash che fungerà da wrapper per i tuoi strumenti e registrerà le informazioni aggiuntive. Ad esempio, log-wrapper.sh:

#!/bin/bash
LOG=~/.claude/hooks.log
INPUT=$(cat)

TOOL=$(echo "$INPUT" |
 jq -r '.tool_name // "n/a"')
EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "n/a"')

echo "=== $(date) | $EVENT | $TOOL ===" >> "$LOG"

echo "$INPUT" | "$1"
CODE=$?

echo "Exit: $CODE" >> "$LOG"
exit $CODE

Questo piccolo script di wrapper acquisisce stdin in una variabile, registra il timestamp e il nome dello strumento e inoltra l'input allo strumento effettivo.

Una volta scritto log-wrapper.sh, dovresti anteporlo alla chiamata dello strumento nell'hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "log-wrapper.sh your-tool-command.py"
          }
        ]
      }
    ]
  }
}

Suggerimento avanzato: per altri suggerimenti sul debug, consulta la documentazione sul debug di Claude Code.

Crea i tuoi hook

Inizia con un semplice hook che risolva un punto di attrito effettivo nel flusso di lavoro. L'hook di formattazione PostToolUse rappresenta una buona prima scelta poiché il feedback è immediato e visibile. Una volta funzionante, espandi in base a ciò che impari.

Per la documentazione di riferimento completa, inclusi tutti i campi disponibili e i pattern avanzati, consulta la documentazione ufficiale sugli hook.

Gli hook ti consentono di personalizzare Claude Code in modo che si adatti al tuo flusso di lavoro, anziché adattarlo allo strumento. Quando investi nella configurazione degli hook, ne trarrai beneficio a ogni sessione.

Inizia a utilizzare gli hook per personalizzare i flussi di lavoro di Claude Code oggi stesso.