Introduction aux hooks

Tout ce que vous avez vu jusqu’ici, vos demandes, CLAUDE.md, les skills, est lu par le modèle, qui décide ensuite quoi en faire. Il suit généralement vos consignes, mais rien ne le garantit. Les hooks jouent un autre rôle : ce sont des commandes que Claude Code, le harnais, exécute lui-même à des moments précis de son cycle de vie. Formater le code après chaque modification, lancer les tests dès qu’un fichier change, interdire l’accès à certains fichiers, vous prévenir quand Claude attend : autant de règles que vous cessez de répéter, parce qu’elles sont appliquées par votre machine, systématiquement et sans négociation possible. « Ne modifie jamais .env » dans CLAUDE.md est une demande ; un hook qui bloque la modification est une garantie.

Comment fonctionnent les hooks

Rappelons le flux normal : votre requête part au modèle avec les définitions d’outils, le modèle répond par un appel d’outil, Claude Code l’exécute et renvoie le résultat, et le cycle se répète jusqu’à la fin de la tâche. Les hooks s’insèrent dans ce processus. Quand un événement se produit, Claude Code lance les hooks qui lui correspondent, leur passe les données de l’événement en JSON sur l’entrée standard, et lit leur verdict dans le code de sortie ou dans du JSON sur la sortie standard. Le point décisif est qu’ils s’exécutent chez vous, pas dans le modèle : ce n’est pas une consigne que Claude pourrait perdre de vue au bout de quarante messages.

Les événements suivent trois cadences :

Il en existe une trentaine en tout : avant et après une compaction, au lancement et à la fin d’un sous-agent, quand une notification part, quand un fichier surveillé change, quand le modèle change… La leçon 17 en dresse l’inventaire. Les deux que vous utiliserez le plus ont des pouvoirs très inégaux :

Un hook a aussi un type. La plupart sont de type command et lancent une commande shell. Quatre autres existent : http envoie les données à une URL ; mcp_tool appelle un outil d’un serveur MCP ; prompt demande à un modèle de trancher en une passe ; agent lance un sous-agent avec des outils pour vérifier l’état réel du code (expérimental).

Où les configurer

Les hooks se déclarent dans les fichiers de réglages, et l’emplacement fixe leur portée :

Une règle de formatage que tout le monde doit respecter va dans le fichier de projet ; une notification de bureau, dans votre fichier utilisateur. Les hooks de tous les niveaux se cumulent, et Claude Code ne les exécute dans un dossier qu’après que vous avez accepté le dialogue de confiance. Vous pouvez les écrire à la main, demander à Claude de les écrire en décrivant ce que vous voulez, ou passer par /hooks, qui liste ceux qui sont configurés, regroupés par événement.

Votre premier hook : être prévenu

Ce hook envoie une notification de bureau quand Claude attend votre réponse ou une permission. Ajoutez-le à ~/.claude/settings.json (version Linux ; sous macOS, remplacez la commande par osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"') :

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

Si le fichier a déjà une clé hooks, ajoutez Notification à côté des événements existants plutôt que de remplacer l’objet. Vérifiez avec /hooks que le hook apparaît, puis testez : passez en mode Manual avec Maj+Tab, demandez quelque chose qui requiert une permission et changez de fenêtre.

Formater après chaque modification

Ce hook PostToolUse lance Prettier sur chaque fichier que Claude modifie. Le matcher limite le hook aux outils d’édition ; la commande extrait le chemin du fichier du JSON reçu avec jq. À placer dans .claude/settings.json du projet :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Quand le hook réussit, rien ne s’affiche dans la conversation : pour vérifier, ouvrez le fichier et constatez le reformatage. Quand plusieurs hooks correspondent au même événement, ils tournent en parallèle, et pour un PreToolUse, c’est la réponse la plus restrictive qui l’emporte (deny avant ask avant allow).

Applications pratiques

Côté PostToolUse : le formatage automatique épargne les diffs pollués par l’indentation, les tests lancés dès qu’un fichier change signalent la régression pendant que Claude a encore la modification en tête, un vérificateur de types joue le même rôle sur la cohérence, et un journal des fichiers modifiés laisse une trace exploitable. Côté PreToolUse : le contrôle d’accès empêche Claude de lire ou de modifier certains fichiers, et la validation vérifie une convention avant qu’un fichier mal nommé n’atterrisse dans le dépôt. Retenez la distinction : PreToolUse contrôle ce que Claude peut faire, PostToolUse améliore ce que Claude a fait.

À vous de jouer

1. Installez le hook de notification dans ~/.claude/settings.json, vérifiez avec /hooks, testez en mode Manual.
2. Installez le hook Prettier dans .claude/settings.json (ou l’équivalent avec votre formateur : black, gofmt, rustfmt). Demandez à Claude d’ajouter une ligne mal formatée à un fichier et ouvrez-le.
3. Demandez à Claude : « Écris un hook PostToolUse qui journalise dans .claude/edits.log le chemin de chaque fichier modifié. » Relisez le JSON qu’il propose avant de l’accepter.

Sources officielles : Automate actions with hooks · Hooks reference · Extend Claude Code

Points clés à retenir

• Un hook est une commande que Claude Code exécute lui-même sur un événement : il s’applique à chaque fois, là où CLAUDE.md n’est qu’une demande
• PreToolUse peut bloquer, autoriser ou réécrire ; PostToolUse donne du feedback sur une action déjà faite
• Types : command (le plus courant), http, mcp_tool, prompt, agent
• L’emplacement fixe la portée : utilisateur, projet, local, organisation, plugin, skill ; /hooks liste ce qui est configuré
• Les hooks d’un dossier ne s’exécutent qu’après le dialogue de confiance