Hooks Claude Code : Automatiser Votre Workflow (Guide Complet 2026)

Les hooks Claude Code, c’est la différence entre un agent qui fait des suggestions et un agent qui respecte vraiment vos règles. Un hook, c’est un petit script qui s’exécute automatiquement à un moment précis de la session : avant un appel d’outil, après une édition, quand vous soumettez un prompt, quand Claude termine sa réponse. Si vous n’utilisez pas les hooks, vous laissez sur la table tout un pan de Claude Code.

Dans ce guide, on voit concrètement ce qu’est un hook, les événements disponibles, comment en écrire un en 3 minutes, 6 hooks que j’utilise réellement, comment bloquer une action dangereuse, et les pièges classiques à éviter. Un hook bien placé vaut 50 rappels dans CLAUDE.md.

Hook, c’est quoi exactement ?

Un hook Claude Code est un script (bash, Python, Node, peu importe) que Claude Code exécute automatiquement à un moment précis. Pensez aux hooks Git : avant un commit, un script tourne, peut rejeter le commit si quelque chose cloche. Les hooks Claude Code, c’est le même principe, mais autour des actions de l’agent.

Vous configurez vos hooks dans .claude/settings.json (projet) ou ~/.claude/settings.json (utilisateur). Chaque hook liste :

• L’événement : quand le hook se déclenche (avant un outil, après une édition, etc.)
• Le matcher : sur quoi il doit se déclencher (un outil précis, tous les outils, certains fichiers, etc.)
• La commande : le script ou la commande shell à exécuter

Le hook peut renvoyer un code de sortie et du JSON pour influencer le comportement de Claude : bloquer l’action, demander une confirmation supplémentaire, injecter un message dans le contexte. C’est un vrai levier, pas juste du logging.

Pourquoi les hooks sont indispensables

Sans hooks, vous comptez sur Claude pour respecter vos règles. Dans 95% des cas, il le fait. Mais pour les 5% restants (la règle est oubliée, mal comprise, contournée), vous avez aucun filet.

Avec hooks, le filet existe au niveau runtime. Exemple concret : vous ne voulez JAMAIS que Claude commit sans avoir lancé les tests. Vous pouvez l’écrire en capitales dans CLAUDE.md, il peut quand même l’oublier un soir. Un hook PreToolUse sur Bash qui détecte git commit et lance les tests avant, c’est impossible à contourner.

Trois bénéfices concrets :

• Contrôle effectif : les règles critiques sont appliquées au niveau runtime, pas au niveau prompt
• Observabilité : vous pouvez logger tout ce que fait Claude pour l’audit ou le debug
• Intégration : vos hooks déclenchent des notifications, des déploiements, des actions dans d’autres systèmes

Un hook bien écrit est aussi la façon la plus fiable d’automatiser un comportement récurrent. « À chaque fois que X, fais Y » : un hook, pas un rappel dans la mémoire utilisateur.

Les événements déclencheurs disponibles

Claude Code expose plusieurs événements auxquels un hook peut s’attacher. Les plus utiles au quotidien :

PreToolUse : AVANT qu’un outil soit exécuté. Vous pouvez inspecter les paramètres, les modifier, bloquer l’action. Idéal pour les garde-fous.

PostToolUse : APRÈS l’exécution d’un outil. Vous voyez le résultat. Idéal pour déclencher une action en chaîne (ex : format après édition, notifier après déploiement).

UserPromptSubmit : quand l’utilisateur soumet un prompt. Vous pouvez enrichir le contexte, logger, ou bloquer si la requête paraît dangereuse.

Stop : quand Claude a fini de répondre. Idéal pour une notification de fin, un récap, un envoi vers un service externe.

SessionStart : au démarrage d’une session. Idéal pour charger des variables d’environnement, vérifier qu’un service est up, afficher un rappel.

SessionEnd : à la fermeture. Idéal pour nettoyer, sauvegarder un log, fermer une connexion.

Il existe aussi Notification (envoi vers un système externe quand Claude réclame l’attention) et SubagentStop (quand un subagent finit). Au total, une dizaine d’événements qui couvrent tout le cycle de vie.

Créer votre premier hook (3 minutes)

On va écrire un hook qui lance prettier automatiquement après chaque édition d’un fichier JS/TS. Simple, utile, introduit la syntaxe.

Étape 1 : éditez settings.json

Ouvrez .claude/settings.json à la racine du projet (créez-le s’il n’existe pas) :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Quelques points :

• PostToolUse : on se déclenche après l’action
• matcher: "Edit|Write" : sur les outils Edit ou Write uniquement
• $CLAUDE_FILE_PATH : variable d’environnement injectée par Claude Code, contient le chemin du fichier modifié
• || true : si prettier échoue (pas applicable au fichier), on n’interrompt pas le workflow

Étape 2 : testez

Demandez à Claude de modifier un fichier TypeScript. Après l’édition, votre hook tourne, prettier reformate, et Claude voit la version formatée au prochain cycle. Magique.

Vous venez d’automatiser un aspect qualité sans jamais avoir à y repenser. Votre CLAUDE.md n’a pas besoin d’évoquer le format : le hook s’en charge.

6 hooks qui blindent un projet

1. Formatter auto après édition (vu plus haut)

Prettier, black, rustfmt selon votre stack. Déclenché sur Edit|Write, cible les extensions pertinentes.

2. Block rm -rf dangereux

Hook PreToolUse sur Bash qui inspecte la commande. Si elle contient rm -rf / ou cible un dossier hors du projet, renvoie un code de sortie non nul = action bloquée. Économise potentiellement une catastrophe.

3. Notification de fin de tâche

Hook Stop qui envoie un ping sur Slack ou une notification système macOS quand Claude a fini. Utile quand vous lancez une grosse tâche et partez en réunion.

4. Audit des commandes shell

Hook PreToolUse sur Bash qui logge chaque commande dans un fichier .claude/audit.log. Historique complet de ce que Claude a fait, horodaté. Précieux quand un truc casse et que vous cherchez pourquoi.

5. Warning sur fichiers sensibles

Hook PreToolUse sur Edit qui vérifie si le fichier modifié est dans une liste sensible (.env, secrets, migrations en prod, etc.). Si oui, bloque et demande confirmation explicite.

6. Inject contexte projet au démarrage

Hook SessionStart qui récupère la version de la base de données, les flags actifs, et les injecte en contexte. Claude sait d’entrée sur quelle version de prod il travaille.

Ce qui revient dans tous ces exemples : le hook encode une règle qu’on ne peut PAS se permettre d’oublier. Le prompt, c’est pour ce qui peut varier. Le hook, c’est pour ce qui ne doit JAMAIS varier.

Bloquer une action avec un hook

Cas crucial : comment rejeter une action dans un hook PreToolUse ?

Deux mécanismes :

Code de sortie non nul

Si votre script renvoie un code ≠ 0, Claude Code bloque l’action. Simple et direct.

#!/bin/bash
# .claude/hooks/check-rm.sh
if echo "$CLAUDE_TOOL_INPUT" | grep -qE "rm\s+-rf"; then
  echo "Interdit : rm -rf détecté" >&2
  exit 1
fi
exit 0

Ce script, branché en PreToolUse sur Bash, bloque toute commande contenant rm -rf. Claude affiche le message d’erreur et ne lance pas la commande.

Retour JSON pour plus de finesse

Pour des cas plus subtils (permettre mais avec avertissement, modifier les paramètres de l’outil, injecter un message), votre hook peut renvoyer un objet JSON structuré sur stdout. Claude Code lit ce JSON et adapte son comportement : bloquer avec un motif, demander une confirmation, modifier le prompt.

Cette flexibilité est ce qui fait des hooks un outil bien plus puissant qu’un simple pre-commit Git.

Hooks vs Skills vs Subagents

Vous avez maintenant trois mécanismes d’extension : skills, subagents, hooks. Comment choisir ?

• Hook : automatique, non négociable. Déclenché par un événement, bloque ou augmente. « Avant tout commit, vérifier X. »
• Skill : invocable, procédural. Claude l’applique quand l’intention correspond. « Prépare un commit propre. »
• Subagent : délégation, exploration isolée. Pour les tâches lourdes qui ne doivent pas polluer le contexte.

Règle pratique :

• Si vous voulez que ça se passe sans demander = hook
• Si vous voulez que Claude propose la procédure = skill
• Si vous voulez un rapport d’exploration = subagent

Et les trois se combinent : un skill peut demander à Claude de lancer un subagent, le tout encadré par des hooks qui loggent et protègent.

Pièges et bonnes pratiques

1. Hook silencieux qui plante

Un hook qui échoue silencieusement est pire que pas de hook. Ajoutez toujours un || true pour les hooks non-critiques, ou loguez les erreurs visiblement.

2. Hook trop lent

Chaque hook se déclenche inline, bloque l’action. Si votre hook prend 10 secondes, chaque édition prend 10 secondes. Optimisez, ou lancez les opérations lourdes en async si possible.

3. Matcher trop large

Un hook branché sur « tous les outils » se déclenche à chaque action. Scope précis = performance meilleure et moins de surprises.

4. Pas de tests

Un hook est du code. Testez-le isolément avant de le mettre en prod. Un hook qui bloque par erreur peut paralyser votre workflow entier.

5. Hooks non versionnés

Les hooks projet dans .claude/settings.json doivent être committés. Sinon vos collègues n’en bénéficient pas. À l’inverse, les hooks personnels restent dans ~/.claude/settings.json.

6. Scripts qui dépendent de votre machine

Un hook qui utilise /Users/ugo/scripts/foo.sh cassera chez vos collègues. Préférez ./scripts/foo.sh relatif au projet. Encore mieux : hook inline dans settings.json pour les cas simples.

7. Debug

Claude Code affiche les sorties des hooks. Si un hook se comporte bizarrement, ajoutez des echo pour voir ce qui se passe. Le contenu de $CLAUDE_TOOL_INPUT et autres variables est loggé dans les outils de debug.

Questions fréquentes

Où documenter la liste exacte des événements et variables ?

La doc officielle Anthropic (docs.claude.com) contient la liste à jour des événements, matchers et variables d’environnement. Elle évolue, donc pour la référence précise c’est la bonne source.

Les hooks fonctionnent-ils dans Claude Desktop ou seulement en CLI ?

Les hooks sont supportés dans les environnements qui embarquent Claude Code, y compris Claude Desktop et les extensions IDE. La config passe par le même .claude/settings.json.

Peut-on écrire un hook en Python ou Node plutôt qu’en Bash ?

Oui. La commande du hook est juste une commande shell. Elle peut pointer vers python3 ./scripts/mon-hook.py ou node ./scripts/mon-hook.js. Tout ce qui tourne depuis un shell est valide.

Un hook peut-il modifier le prompt utilisateur avant que Claude le voie ?

Oui, via UserPromptSubmit qui peut enrichir ou modifier le prompt via retour JSON. Utile pour injecter du contexte automatique (numéro de ticket Linear courant, branche git, etc.).

Combien de hooks peut-on cumuler sur un même événement ?

Autant que nécessaire. Ils s’exécutent en séquence. Un échec dans l’un coupe la chaîne (si exit 1). Tenez les courts.

Les hooks consomment-ils mon quota Claude ?

Non. Un hook est un script local exécuté par Claude Code, pas un appel au modèle. Il est donc gratuit. Ce qui peut coûter, c’est si le hook pousse du contenu en contexte (via JSON retour) et que ça allonge la conversation.

Peut-on désactiver temporairement les hooks ?

Oui, en commentant/supprimant l’entrée dans settings.json. Ou en utilisant un flag d’environnement dans le script (if [ "$SKIP_HOOKS" ] ; then exit 0 ; fi). Pratique pour débugger.

En résumé

Les hooks sont ce qui transforme Claude Code d’un « assistant intelligent » en un « agent conforme à vos règles ». Ce que vous ne pouvez pas vous permettre d’oublier, ne le laissez pas au prompt : mettez-le dans un hook.

Commencez petit : un hook de formattage auto, un hook de protection contre rm -rf, un hook de notification en fin de tâche. Trois hooks, 15 minutes à écrire, gain pour des années.

Pour découvrir les autres briques avancées qui entourent les hooks, voyez notre guide complet Claude Code qui couvre CLAUDE.md, Plan Mode, MCP, subagents et skills.