Inizia con i hook di Claude Code

Gli hook di Claude Code sono comandi shell definiti dall’utente che vengono eseguiti in vari punti del ciclo di vita di Claude Code. Gli hook forniscono controllo deterministico sul comportamento di Claude Code, garantendo che certe azioni avvengano sempre piuttosto che affidarsi al LLM per scegliere di eseguirle.

Esempi di casi d’uso per gli hook includono:

• Notifiche: Personalizza come ricevi notifiche quando Claude Code è in attesa del tuo input o permesso per eseguire qualcosa.
• Formattazione automatica: Esegui prettier sui file .ts, gofmt sui file .go, ecc. dopo ogni modifica di file.
• Logging: Traccia e conta tutti i comandi eseguiti per conformità o debugging.
• Feedback: Fornisci feedback automatizzato quando Claude Code produce codice che non segue le convenzioni della tua codebase.
• Permessi personalizzati: Blocca modifiche ai file di produzione o directory sensibili.

Codificando queste regole come hook piuttosto che istruzioni di prompt, trasformi suggerimenti in codice a livello di app che viene eseguito ogni volta che è previsto che venga eseguito.

​

Panoramica degli Eventi Hook

Claude Code fornisce diversi eventi hook che vengono eseguiti in punti diversi del flusso di lavoro:

• PreToolUse: Viene eseguito prima delle chiamate agli strumenti (può bloccarle)
• PostToolUse: Viene eseguito dopo il completamento delle chiamate agli strumenti
• Notification: Viene eseguito quando Claude Code invia notifiche
• Stop: Viene eseguito quando Claude Code finisce di rispondere
• SubagentStop: Viene eseguito quando i task del subagent si completano

Ogni evento riceve dati diversi e può controllare il comportamento di Claude in modi diversi.

​

Quickstart

In questo quickstart, aggiungerai un hook che registra i comandi shell che Claude Code esegue.

​

Prerequisiti

Installa jq per l’elaborazione JSON nella riga di comando.

​

Passo 1: Apri la configurazione degli hook

Esegui il comando slash /hooks e seleziona l’evento hook PreToolUse.

Gli hook PreToolUse vengono eseguiti prima delle chiamate agli strumenti e possono bloccarle fornendo a Claude feedback su cosa fare diversamente.

​

Passo 2: Aggiungi un matcher

Seleziona + Add new matcher… per eseguire il tuo hook solo sulle chiamate agli strumenti Bash.

Digita Bash per il matcher.

​

Passo 3: Aggiungi l’hook

Seleziona + Add new hook… e inserisci questo comando:

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​

Passo 4: Salva la tua configurazione

Per la posizione di archiviazione, seleziona User settings dato che stai registrando nella tua directory home. Questo hook si applicherà quindi a tutti i progetti, non solo al tuo progetto attuale.

Poi premi Esc finché non torni al REPL. Il tuo hook è ora registrato!

​

Passo 5: Verifica il tuo hook

Esegui di nuovo /hooks o controlla ~/.claude/settings.json per vedere la tua configurazione:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​

Passo 6: Testa il tuo hook

Chiedi a Claude di eseguire un comando semplice come ls e controlla il tuo file di log:

cat ~/.claude/bash-command-log.txt

Dovresti vedere voci come:

ls - Lists files and directories

​

Altri Esempi

​

Hook di Formattazione Codice

Formatta automaticamente i file TypeScript dopo la modifica:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$(.tool_input.file_path)' | grep -q '\\.ts$'; then npx prettier --write '$(.tool_input.file_path)'; fi"
          }
        ]
      }
    ]
  }
}

​

Hook di Notifica Personalizzato

Ricevi notifiche desktop quando Claude ha bisogno di input:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Awaiting your input'"
          }
        ]
      }
    ]
  }
}

​

Hook di Protezione File

Blocca modifiche ai file sensibili:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​

Scopri di più

• Per la documentazione di riferimento sugli hook, vedi Riferimento hook.
• Per le migliori pratiche di sicurezza complete e linee guida sulla sicurezza, vedi Considerazioni sulla Sicurezza nella documentazione di riferimento degli hook.
• Per i passaggi di risoluzione dei problemi e tecniche di debugging, vedi Debugging nella documentazione di riferimento degli hook.