Claude Code Hooks : Automatiser ton Workflow de Développement

Mis à jour le 3 mars 2026

Les hooks sont le système d'automatisation le plus puissant de Claude Code. À chaque action — avant d'exécuter une commande, après avoir modifié un fichier, quand la session se termine — tu peux déclencher automatiquement du code. Auto-format, validation de sécurité, notifications, logs. Sans jamais y penser.

Là où le fichier CLAUDE.md donne des instructions que Claude Code peut choisir de suivre, les hooks sont du code machine. Ils s'exécutent à chaque fois, sans exception. C'est la différence entre dire "s'il te plaît, formate le code" et brancher un formateur automatique qui se déclenche à chaque modification. Ce guide t'explique tout : les événements disponibles, comment configurer tes hooks, et les 5 hooks indispensables à mettre en place dès maintenant.

C'est quoi un hook Claude Code

Un hook est un script qui s'exécute automatiquement à un moment précis du cycle de vie de Claude Code. Avant qu'un outil soit utilisé (PreToolUse), après (PostToolUse), à la fin de la session (Stop), ou quand un sub-agent démarre (SubagentStart). C'est de l'automatisation garantie.

Le concept est simple : tu définis un événement déclencheur et un script à exécuter. Quand l'événement se produit, le script se lance. Pas de demande de permission, pas d'oubli, pas de variation. Le script s'exécute. Point.

C'est la différence fondamentale avec le fichier CLAUDE.md. Quand tu écris dans ton CLAUDE.md "Formate toujours le code avec Prettier", c'est une suggestion. Claude Code la suit la plupart du temps, mais c'est du texte que le modèle interprète. Il peut l'oublier, l'ignorer dans un cas particulier, ou l'appliquer de manière incohérente.

Un hook, c'est du code. Si tu configures un hook PostToolUse qui lance Prettier après chaque modification de fichier, Prettier se lancera. À chaque fois. Sans exception. Le hook ne passe pas par l'interprétation du modèle — il passe par le système d'exécution de Claude Code. C'est de l'enforcement, pas de la guidance.

En résumé : CLAUDE.md = suggestions que Claude Code peut ignorer. Hooks = exécution garantie, contrôlée par des codes de sortie.

Les événements disponibles

Claude Code expose plusieurs événements dans son cycle de vie. Chaque événement est un point d'accroche où tu peux injecter ton propre code. Voici les principaux.

PreToolUse — Avant l'action

C'est l'événement le plus stratégique. Il se déclenche avant que Claude Code utilise un outil : Write, Edit, Bash, ou n'importe quel autre. Ton hook reçoit les détails de l'action prévue (quel outil, quels arguments) et peut décider de la laisser passer ou de la bloquer.

Le contrôle se fait par le code de sortie (exit code) du script :

• Exit 0 — L'action est autorisée, Claude Code continue normalement.
• Exit 1 — Erreur du hook lui-même. Claude Code signale le problème mais continue.
• Exit 2 — L'action est bloquée. Claude Code affiche le message d'erreur que ton hook renvoie sur stdout et l'action ne s'exécute pas.

Cas d'usage typiques : bloquer des commandes dangereuses (rm -rf /, git push --force), valider que les fichiers sensibles ne sont pas modifiés sans confirmation, empêcher l'exécution de certaines commandes en production.

PostToolUse — Après l'action

Se déclenche une fois que l'outil a terminé son exécution. Ton hook reçoit le résultat de l'action. C'est l'endroit idéal pour des traitements post-action : formater le code qui vient d'être écrit, logger les modifications, mettre à jour un fichier de suivi.

Cas d'usage typiques : lancer Prettier ou Black après chaque Write/Edit, ajouter une entrée de log après chaque commande Bash, vérifier que le code modifié compile toujours.

Stop — Fin de session

Se déclenche quand Claude Code termine une session — soit parce que la tâche est finie, soit parce que tu quittes. C'est le moment de faire le ménage : envoyer une notification, générer un résumé des changements, déclencher un commit automatique.

Cas d'usage typiques : notification macOS/Slack quand la session se termine, résumé des fichiers modifiés, auto-commit des changements en cours.

SubagentStart / SubagentStop

Ces événements se déclenchent quand Claude Code lance un sub-agent (un agent spécialisé qui travaille en parallèle). SubagentStart se déclenche au lancement, SubagentStop à la fin. C'est utile pour monitorer l'utilisation des sub-agents, gérer les ressources, ou logger leur activité.

Notification

Se déclenche quand Claude Code a besoin de ton attention — par exemple quand il attend une réponse ou une confirmation. C'est l'événement parfait pour envoyer une alerte sonore ou une notification système quand tu es sur un autre écran.

UserPromptSubmit

Se déclenche quand tu soumets un prompt à Claude Code. Tu peux l'utiliser pour injecter du contexte automatique, enrichir le prompt avec des informations du projet, ou logger les interactions.

PreCompact

Se déclenche avant que Claude Code compacte son contexte (quand la conversation devient trop longue). C'est le bon moment pour sauvegarder un snapshot de l'état actuel avant que des informations soient résumées.

Les types de handlers

Un handler, c'est le code qui s'exécute quand l'événement se déclenche. Claude Code propose quatre types de handlers différents, selon ce que tu veux faire.

type: command — Script shell

Le type le plus courant. Tu définis une commande shell qui sera exécutée. Ça peut être un script Bash, un appel à un outil CLI, ou n'importe quelle commande système. L'événement est passé en entrée via stdin au format JSON.

{
  "type": "command",
  "command": "bash /path/to/my-hook.sh"
}

C'est le type à utiliser pour 90 % des cas : formatage, validation, notifications système, logging.

type: http — Webhook HTTP POST

Envoie une requête HTTP POST à une URL avec les données de l'événement en JSON. Parfait pour intégrer Claude Code avec des services externes : Slack, Discord, un dashboard interne, un système de monitoring.

{
  "type": "http",
  "url": "https://hooks.slack.com/services/xxx/yyy/zzz"
}

type: prompt — Évaluation LLM

Le handler est un prompt qui sera évalué par le modèle de langage. Le résultat est retourné en JSON. C'est utile pour des validations intelligentes qui nécessitent une compréhension du contexte.

type: mcp-tool — Outil MCP

Exécute un outil MCP (Model Context Protocol) comme handler. Si tu as des serveurs MCP configurés avec des outils spécifiques, tu peux les déclencher automatiquement via des hooks.

Configurer ses hooks

Les hooks se configurent dans un fichier JSON. Tu as deux options de placement, selon que tu veux des hooks locaux au projet ou globaux.

Emplacement des fichiers

Pour des hooks spécifiques au projet, crée un fichier .claude/hooks.json à la racine de ton projet. Pour des hooks globaux (qui s'appliquent à tous tes projets), ajoute-les dans la section hooks de ton fichier ~/.claude/settings.json.

Structure JSON

La structure est un objet dont les clés sont les noms d'événements, et les valeurs sont des tableaux de handlers :

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "bash .claude/hooks/security-guard.sh",
        "matcher": "Bash",
        "timeout": 5000
      }
    ],
    "PostToolUse": [
      {
        "type": "command",
        "command": "bash .claude/hooks/auto-format.sh",
        "matcher": "Write|Edit"
      }
    ],
    "Notification": [
      {
        "type": "command",
        "command": "bash .claude/hooks/notify.sh",
        "async": true
      }
    ]
  }
}

Les matchers

Le champ matcher permet de filtrer sur quel outil le hook se déclenche. Tu peux spécifier un nom d'outil exact ("Bash"), plusieurs outils avec un pipe ("Write|Edit"), ou omettre le champ pour déclencher le hook sur tous les outils.

Options avancées

• async: true — Le hook s'exécute en parallèle sans bloquer Claude Code. Indispensable pour les notifications et les logs qui ne doivent pas ralentir le workflow.
• timeout — Durée maximale d'exécution en millisecondes. Si le hook dépasse ce temps, il est tué. Protège contre les scripts qui plantent ou les requêtes HTTP qui ne répondent pas.

Les codes de sortie

Pour les hooks PreToolUse, le code de sortie contrôle le flux :

• Exit 0 — Tout va bien, l'action continue.
• Exit 1 — Erreur du hook (le hook lui-même a planté). Claude Code continue mais signale le problème.
• Exit 2 — Blocage intentionnel. L'action est annulée. Le texte sur stdout est affiché comme message d'erreur à Claude Code.

5 hooks indispensables

Assez de théorie. Voici 5 hooks concrets que tu peux mettre en place aujourd'hui. Chacun résout un problème réel et fréquent.

1. Auto-format après chaque modification

Le hook le plus utile. Chaque fichier modifié par Claude Code passe automatiquement par Prettier (JavaScript/TypeScript) ou Black (Python). Fini le code mal formaté.

// .claude/hooks/auto-format.sh
#!/bin/bash
# Récupère le chemin du fichier modifié depuis stdin (JSON)
FILE=$(cat | jq -r '.tool_input.file_path // empty')

if [ -z "$FILE" ]; then
  exit 0
fi

# Détecte l'extension et formate
case "$FILE" in
  *.js|*.ts|*.jsx|*.tsx|*.json|*.css)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
  *.py)
    black "$FILE" 2>/dev/null
    ;;
esac

exit 0

Hook config : PostToolUse, matcher "Write|Edit".

2. Security guard — bloquer les commandes dangereuses

Un filet de sécurité qui empêche Claude Code d'exécuter des commandes destructrices. Indispensable si tu donnes des permissions larges à Claude Code.

// .claude/hooks/security-guard.sh
#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty')

# Liste des patterns dangereux
BLOCKED_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "git push --force"
  "git push -f"
  "DROP TABLE"
  "DROP DATABASE"
  "> /dev/sda"
)

for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qi "$pattern"; then
    echo "BLOQUÉ : commande dangereuse détectée ($pattern)"
    exit 2
  fi
done

exit 0

Hook config : PreToolUse, matcher "Bash". Le exit 2 bloque l'action et affiche le message.

3. Notification quand Claude Code attend

Quand tu travailles sur autre chose et que Claude Code a besoin de ton attention, ce hook envoie une notification macOS avec un son. Tu ne rates plus jamais une question de Claude Code.

// .claude/hooks/notify.sh
#!/bin/bash
osascript -e 'display notification "Claude Code a besoin de toi" with title "LE LABO IA" sound name "Ping"'

Hook config : Notification, async: true. Le async est important ici — la notification ne doit pas bloquer Claude Code.

4. Protection des fichiers sensibles

Empêche Claude Code de modifier des fichiers critiques (.env, fichiers de credentials, configurations de production) sans que tu aies explicitement validé.

// .claude/hooks/file-protect.sh
#!/bin/bash
FILE=$(cat | jq -r '.tool_input.file_path // empty')

# Fichiers protégés
PROTECTED_PATTERNS=(".env" "credentials" "secret" "production.json" ".pem" ".key")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if echo "$FILE" | grep -qi "$pattern"; then
    echo "BLOQUÉ : fichier sensible ($FILE). Modifie-le manuellement."
    exit 2
  fi
done

exit 0

Hook config : PreToolUse, matcher "Write|Edit". Toute tentative de modification d'un fichier sensible sera bloquée avec un message explicite.

5. Notification de fin de session

Quand Claude Code termine une tâche longue, tu reçois une alerte. Plus besoin de vérifier manuellement si c'est fini.

// .claude/hooks/task-done.sh
#!/bin/bash
osascript -e 'display notification "Tâche terminée ✓" with title "Claude Code" sound name "Glass"'

Hook config : Stop, async: true.

Ces 5 hooks couvrent les besoins fondamentaux : qualité du code (auto-format), sécurité (guard + file-protect), et expérience utilisateur (notifications). C'est un excellent point de départ avant d'aller vers des hooks plus avancés.

Si tu veux créer des commandes personnalisées et des skills pour compléter tes hooks, c'est l'étape suivante logique. Les hooks automatisent, les skills et commandes te donnent des capacités à la demande.

Hooks vs CLAUDE.md : quand utiliser quoi

Les hooks et le fichier CLAUDE.md sont complémentaires, mais ils servent des objectifs très différents. Voici comment choisir.

La règle est simple : si c'est critique et que ça ne doit jamais être ignoré (sécurité, formatage, notifications), utilise un hook. Si c'est une préférence, une convention, ou du contexte que Claude Code doit connaître, utilise le CLAUDE.md.

Les deux systèmes ensemble forment un setup complet. Le CLAUDE.md dit à Claude Code comment tu veux travailler. Les hooks s'assurent que certaines règles sont appliquées mécaniquement, sans dépendre de la bonne volonté du modèle.

Pour une vue d'ensemble de tout l'écosystème Claude Code — hooks, skills, CLAUDE.md, MCP, permissions — consulte le guide complet de Claude Code. Et si tu débutes en automatisation, les hooks sont un excellent premier pas vers un workflow professionnel.

Tu peux aussi combiner les hooks avec le workflow Claude Code pour entrepreneurs pour industrialiser ta production de code tout en gardant le contrôle sur la qualité et la sécurité.

Meydeey — Architecte IA & Automatisation

+110 entrepreneurs formés au Vibe Coding et à l'automatisation IA avec N8N. Fondateur du Labo IA.