Les hooks Claude Code : guide complet avec cas pratiques

Les hooks Claude Code sont des commandes shell qui s’exécutent automatiquement avant ou après une action de l’assistant, ce qui permet de l’autoriser, la bloquer, ou la compléter sans intervention manuelle. Contrairement à un fichier CLAUDE.md, qui reste une instruction que Claude peut interpréter, un hook s’applique de façon systématique, quelle que soit la décision de l’IA.

Qu’est-ce qu’un hook dans Claude Code ?

Un hook Claude Code est une commande déclenchée à un point précis du cycle de vie d’une session, par exemple juste avant qu’un outil ne s’exécute, ou juste après. Cette commande reçoit des informations sur l’action en cours via l’entrée standard, et communique sa décision via son code de sortie et, si besoin, une sortie JSON structurée.

Ce mécanisme rappelle les hooks Git (pre-commit, pre-push), mais appliqué à chaque action de l’agent, pas seulement aux opérations Git. Un formatage automatique après édition, un blocage de fichier sensible, ou une vérification de type avant de continuer sont autant de cas d’usage typiques.

Comment configurer un hook dans Claude Code ?

Les hooks se déclarent dans un fichier de paramètres, .claude/settings.json pour un hook partagé avec l’équipe, ou ~/.claude/settings.json pour un hook personnel valable sur tous vos projets. Chaque entrée précise l’événement concerné, un motif optionnel pour cibler certains outils, puis la commande à exécuter.

Voici la structure de base pour un hook qui se déclenche avant l’utilisation de l’outil Bash :

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "node /chemin/vers/mon-hook.js" } ] } ] } }

Privilégiez des chemins absolus pour vos scripts, ce qui évite les erreurs liées au dossier de travail et facilite le partage du fichier de configuration en équipe.

Que reçoit un hook en entrée ?

Un hook reçoit un objet JSON via l’entrée standard, dont le contenu varie selon l’événement et l’outil concerné. Pour un hook PreToolUse ou PostToolUse, cet objet contient notamment tool_name, tool_input avec les arguments envoyés à l’outil, et pour PostToolUse, tool_response avec le résultat obtenu.

Chaque outil a sa propre structure : l’outil Read envoie un champ file_path, l’outil Bash envoie un champ command. Si vous ne connaissez pas la structure exacte, un hook générique qui écrit l’entrée reçue dans un fichier journal permet de l’inspecter avant d’écrire la logique définitive.

Comment un hook bloque-t-il une action avec les codes de sortie ?

Le code de sortie de votre commande indique à Claude Code si l’action doit se poursuivre. Un code 0 signifie que tout va bien, et Claude Code lit alors une éventuelle sortie JSON sur la sortie standard pour un contrôle plus fin. Un code 2 est une erreur bloquante : pour un hook PreToolUse, cela empêche l’appel d’outil, et le contenu envoyé sur la sortie d’erreur est transmis à Claude comme motif du blocage.

Tout autre code de sortie est traité comme une erreur non bloquante pour la plupart des événements : l’action se poursuit, mais un message d’erreur apparaît dans la conversation. Un hook de sécurité doit donc systématiquement utiliser le code 2, sans quoi il n’a aucun effet réellement contraignant.

Quels sont les principaux événements de hook disponibles ?

Claude Code propose une trentaine d’événements de hook, mais quelques-uns couvrent l’essentiel des besoins courants. PreToolUse se déclenche avant chaque appel d’outil et peut le bloquer ; PostToolUse se déclenche après un appel réussi et permet des actions de suivi comme le formatage.

• UserPromptSubmit : se déclenche quand vous envoyez un message, avant que Claude ne le traite.
• Stop et SubagentStop : se déclenchent quand Claude, ou un sous-agent, termine sa réponse.
• SessionStart et SessionEnd : se déclenchent au démarrage ou à la fin d’une session.
• Notification : se déclenche quand Claude Code envoie une notification, par exemple une demande de permission.
• PreCompact : se déclenche avant une opération de compactage de la conversation.

Cas pratique : bloquer la lecture des fichiers .env

Pour empêcher Claude Code d’ouvrir vos fichiers .env, ajoutez un hook PreToolUse ciblant l’outil Read dans votre fichier de settings :

{ "hooks": { "PreToolUse": [ { "matcher": "Read", "hooks": [ { "type": "command", "command": "node $PWD/hooks/read_hook.js" } ] } ] } }

Le script lit l’entrée JSON, extrait tool_input.file_path, et quitte avec le code 2 si le chemin contient .env, en écrivant un message explicatif sur la sortie d’erreur. Ce hook ne couvre que l’outil Read : pour bloquer aussi une lecture via Grep ou une commande cat .env dans Bash, il faut soit ajouter des hooks dédiés à chaque outil avec leur propre format d’entrée, soit combiner cette approche avec une règle permissions.deny comme Read(**/.env), qui s’applique de façon uniforme.

Cas pratique : vérifier le typage TypeScript après chaque modification

Un problème fréquent survient quand Claude modifie la signature d’une fonction sans mettre à jour tous ses points d’appel dans le projet. Un hook PostToolUse qui lance le compilateur TypeScript après chaque édition permet de détecter ces erreurs immédiatement plutôt qu’en fin de tâche :

{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx tsc --noEmit", "timeout": 60 } ] } ] } }

Les erreurs de typage détectées remontent dans la conversation, ce qui pousse Claude à corriger les fichiers concernés avant de continuer. Cette approche fonctionne pour tout langage typé disposant d’un vérificateur en ligne de commande ; pour un langage non typé, une exécution ciblée des tests automatisés joue un rôle équivalent.

Cas pratique : éviter la duplication de requêtes avec une revue automatique

Sur un projet volumineux avec de nombreuses fonctions de requête en base de données, Claude peut parfois recréer une fonction qui existe déjà plutôt que de réutiliser l’existante. Un hook PostToolUse ciblant les modifications dans un dossier de requêtes peut lancer une revue automatisée via une session Claude Code en mode non interactif, par exemple avec claude -p "vérifie si cette modification duplique une fonction existante dans ce dossier", dont la réponse est ensuite transmise à la session principale comme retour.

Cette approche coûte davantage en temps et en usage, puisqu’elle déclenche une seconde session à chaque modification. Réservez-la aux dossiers vraiment critiques, où la cohérence du code justifie ce surcoût.

PreToolUse ou PostToolUse : lequel choisir ?

Choisissez PreToolUse quand vous voulez empêcher une action avant qu’elle ne se produise, comme la lecture d’un fichier sensible ou une commande destructrice. Choisissez PostToolUse quand l’action elle-même est acceptable mais que vous voulez la compléter ou la vérifier après coup, comme un formatage de code ou une vérification de type.

PostToolUse ne peut pas annuler une action déjà effectuée : il ne fait que remonter un message à Claude, qui devra corriger dans un tour suivant si nécessaire.

Ce qu’il faut retenir sur les hooks Claude Code

Les hooks apportent un contrôle déterministe que CLAUDE.md ne peut pas garantir, puisqu’ils s’exécutent systématiquement plutôt que d’être une simple instruction que le modèle interprète. Réservez PreToolUse aux blocages de sécurité, PostToolUse aux vérifications et au formatage, et testez toujours vos scripts avec une entrée JSON simulée avant de les déployer en équipe.

Pour la référence complète des événements disponibles et du format d’entrée et de sortie, consultez la documentation officielle des hooks Claude Code.

Questions fréquentes