Commencer avec les hooks Claude Code

Les hooks Claude Code sont des commandes shell définies par l’utilisateur qui s’exécutent à différents moments du cycle de vie de Claude Code. Les hooks fournissent un contrôle déterministe sur le comportement de Claude Code, garantissant que certaines actions se produisent toujours plutôt que de compter sur le LLM pour choisir de les exécuter.

Exemples de cas d’usage pour les hooks incluent :

• Notifications : Personnalisez la façon dont vous êtes notifié lorsque Claude Code attend votre saisie ou permission pour exécuter quelque chose.
• Formatage automatique : Exécutez prettier sur les fichiers .ts, gofmt sur les fichiers .go, etc. après chaque modification de fichier.
• Journalisation : Suivez et comptez toutes les commandes exécutées pour la conformité ou le débogage.
• Retour d’information : Fournissez un retour automatisé lorsque Claude Code produit du code qui ne suit pas les conventions de votre base de code.
• Permissions personnalisées : Bloquez les modifications aux fichiers de production ou aux répertoires sensibles.

En encodant ces règles comme hooks plutôt que comme instructions de prompt, vous transformez les suggestions en code au niveau de l’application qui s’exécute chaque fois qu’il est censé s’exécuter.

​

Aperçu des événements de hooks

Claude Code fournit plusieurs événements de hooks qui s’exécutent à différents points du flux de travail :

• PreToolUse : S’exécute avant les appels d’outils (peut les bloquer)
• PostToolUse : S’exécute après la completion des appels d’outils
• Notification : S’exécute lorsque Claude Code envoie des notifications
• Stop : S’exécute lorsque Claude Code termine de répondre
• SubagentStop : S’exécute lorsque les tâches de sous-agent se terminent

Chaque événement reçoit des données différentes et peut contrôler le comportement de Claude de différentes manières.

​

Démarrage rapide

Dans ce démarrage rapide, vous ajouterez un hook qui journalise les commandes shell que Claude Code exécute.

​

Prérequis

Installez jq pour le traitement JSON en ligne de commande.

​

Étape 1 : Ouvrir la configuration des hooks

Exécutez la commande slash /hooks et sélectionnez l’événement de hook PreToolUse.

Les hooks PreToolUse s’exécutent avant les appels d’outils et peuvent les bloquer tout en fournissant à Claude un retour sur ce qu’il faut faire différemment.

​

Étape 2 : Ajouter un matcher

Sélectionnez + Add new matcher… pour exécuter votre hook uniquement sur les appels d’outils Bash.

Tapez Bash pour le matcher.

​

Étape 3 : Ajouter le hook

Sélectionnez + Add new hook… et entrez cette commande :

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

​

Étape 4 : Sauvegarder votre configuration

Pour l’emplacement de stockage, sélectionnez User settings puisque vous journalisez dans votre répertoire personnel. Ce hook s’appliquera alors à tous les projets, pas seulement à votre projet actuel.

Puis appuyez sur Esc jusqu’à ce que vous retourniez au REPL. Votre hook est maintenant enregistré !

​

Étape 5 : Vérifier votre hook

Exécutez /hooks à nouveau ou vérifiez ~/.claude/settings.json pour voir votre configuration :

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

​

Étape 6 : Tester votre hook

Demandez à Claude d’exécuter une commande simple comme ls et vérifiez votre fichier de log :

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

Vous devriez voir des entrées comme :

ls - Lists files and directories

​

Plus d’exemples

​

Hook de formatage de code

Formatez automatiquement les fichiers TypeScript après modification :

{
  "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 de notification personnalisée

Obtenez des notifications de bureau lorsque Claude a besoin d’une saisie :

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

​

Hook de protection de fichiers

Bloquez les modifications aux fichiers sensibles :

{
  "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)\""
          }
        ]
      }
    ]
  }
}

​

En savoir plus

• Pour la documentation de référence sur les hooks, voir Référence des hooks.
• Pour les meilleures pratiques de sécurité complètes et les directives de sécurité, voir Considérations de sécurité dans la documentation de référence des hooks.
• Pour les étapes de dépannage et les techniques de débogage, voir Débogage dans la documentation de référence des hooks.