Les 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. Ce qui doit arriver à chaque fois, sans exception, relève d’un hook.

Déterministe ou non

La documentation range toute instruction dans l’une de deux catégories :

• non déterministe : vous écrivez l’instruction, le modèle la lit et décide (un prompt, CLAUDE.md, une skill) ;
• déterministe : vous la configurez, et Claude Code est obligé de l’exécuter (un hook, une règle de refus, un réglage géré par l’organisation).

Prenez trois règles qu’on trouve souvent dans un CLAUDE.md : « ne jamais lire .env », « toujours lancer le formateur après une modification », « ne pas toucher au dossier des migrations ». Claude les suivra presque toujours. Quand « presque » ne suffit pas, il faut les sortir de CLAUDE.md pour en faire un hook ou une règle de permission.

Les événements

Un hook se rattache à un événement. Les plus utiles pour commencer :

Il en existe bien d’autres, par exemple avant et après une compaction, ou au lancement et à la fin d’un sous-agent ; la commande /hooks liste ceux que vous avez configurés, regroupés par événement.

Votre premier hook : être prévenu

Ce hook vous envoie une notification de bureau quand Claude attend votre réponse. Ajoutez-le à ~/.claude/settings.json (version Linux ; sous macOS, la commande utilise osascript) :

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

Vérifiez ensuite avec /hooks qu’il apparaît sous Notification. Vous pouvez aussi demander à Claude d’écrire le hook pour vous, en décrivant ce que vous voulez.

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 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"
          }
        ]
      }
    ]
  }
}

Bloquer une action : le code de sortie 2

Un hook reçoit les détails de l’événement en JSON sur son entrée standard. Son code de sortie décide de la suite :

• 0 : pas d’objection. Pour un PreToolUse, l’appel continue son parcours normal de permissions : sortir avec 0 ne l’approuve pas.
• 2 : blocage. Ce que le script écrit sur la sortie d’erreur est renvoyé à Claude comme explication, pour qu’il change d’approche.

C’est ce que fait l’exemple officiel de protection de fichiers : un script appelé par un hook PreToolUse sur Edit|Write compare le chemin à une liste (.env, package-lock.json, .git/) et sort avec le code 2 s’il correspond. Le même principe, appliqué à l’événement Stop, empêche Claude de terminer tant qu’une vérification échoue :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Si le typage échoue, les erreurs du compilateur repartent vers Claude, qui continue jusqu’à ce que tsc passe.

Où placer un hook

Une précaution

La documentation de référence le dit en avertissement : un hook de type command exécute des commandes shell avec toutes les permissions de votre compte utilisateur ; il peut modifier, supprimer ou lire tout fichier auquel votre compte a accès. Relisez et testez chaque hook avant de l’ajouter, surtout s’il vient d’un dépôt que vous n’avez pas écrit. En session interactive, Claude Code retient les hooks tant que vous n’avez pas accepté la boîte de dialogue de confiance du dossier ; avec claude -p, en revanche, cette boîte n’apparaît pas et les hooks commités dans le dépôt s’exécutent. Il existe d’autres types de hooks (http, mcp_tool, prompt, agent) ; les deux derniers font décider un modèle et ne sont donc pas déterministes.

À vous de jouer

Un hook de formatage. Ajoutez un hook PostToolUse qui lance votre formateur après chaque modification de fichier par Edit ou Write. Vérifiez-le avec /hooks, demandez une petite modification, et contrôlez que le fichier est bien formaté sans que vous l’ayez demandé à Claude.

Sources officielles : Hooks (Claude Academy) · Automate actions with hooks · Hooks reference · Best practices

Points clés à retenir

• Un hook est exécuté par Claude Code lui-même : c’est l’outil des règles sans exception, là où CLAUDE.md reste une consigne
• Événements clés : PreToolUse (avant un outil, peut bloquer), PostToolUse, Notification, Stop, SessionStart
• Code de sortie 2 = blocage, et la sortie d’erreur est renvoyée à Claude ; 0 = pas d’objection, sans approuver pour autant
• Les hooks se déclarent dans les fichiers settings.json ; /hooks les liste
• Relisez tout hook avant de l’activer : il s’exécute avec vos droits