Un hook, c'est un réflexe que Claude ne peut pas oublier

La règle que j'avais écrite

Dans le fichier CLAUDE.md de ce site, une ligne dit : « Ne jamais lire ni afficher .env ». Ce fichier contient mes clés secrètes, dont celles de Stripe, le service de paiement. Et mes vidéos montrent mon écran, terminal compris. Une clé affichée une seconde, c'est une clé publiée.

Cette ligne est une consigne : du texte que Claude lit au début de chaque session. Le fichier CLAUDE.md est tout le sujet de la formation CLAUDE.md : ne plus jamais tout réexpliquer. La documentation officielle de Claude Code dit clairement ce qu'elle vaut. CLAUDE.md, c'est « du contexte, pas une configuration appliquée ». Claude le lit et essaie de le suivre, mais sans « garantie de respect strict ».

Essayer, ça suffit pour une convention de nommage. Pour une clé secrète, non.

Ce que la documentation conseille

La même page donne la solution. Si une consigne doit s'appliquer à un moment précis, « avant chaque commit ou après chaque modification de fichier », il faut l'écrire comme un hook. Les hooks, dit-elle, s'appliquent « quoi que Claude décide de faire ».

Un hook est une commande que Claude Code lance lui-même, à un moment fixe de la session. Attention à la nuance : c'est le programme Claude Code qui le lance, pas Claude, le modèle qui réfléchit. Le modèle n'a pas à y penser. Il ne peut donc pas l'oublier.

Un réflexe, pas un pense-bête

Pense à la différence entre un pense-bête collé sur le frigo et le réflexe qui retire ta main d'une plaque chaude. Le pense-bête, tu peux passer devant sans le lire. Le réflexe se déclenche sans que tu y penses.

Un hook, c'est le réflexe. Il se déclenche sur un événement, un moment précis de la session : juste avant que Claude utilise un outil, juste après, quand tu envoies ta demande, quand Claude a fini de répondre. Un outil, c'est une action de Claude : lire un fichier, le modifier, lancer une commande.

À chaque événement, Claude Code envoie au hook la description de ce qui se passe, en JSON : un format de texte structuré, avec des accolades et des guillemets. Le hook fait son travail, puis répond par un code de sortie, le nombre qu'un programme renvoie en se terminant (0 quand tout va bien). Il peut aussi répondre par un message.

Ce qu'un hook sait faire

Trois familles couvrent presque tout :

• Dire non. Avant une action, le hook peut la refuser et expliquer pourquoi à Claude. C'est ce qui protège un fichier .env pour de bon.
• Agir après coup. Après une modification, il peut formater le fichier, lancer les tests ou tenir un journal. À chaque fois, pas seulement quand Claude y pense.
• Informer. Au démarrage ou à l'envoi d'une demande, il peut donner une information à Claude. Quand Claude t'attend, il peut te prévenir.

Une limite à connaître dès maintenant : un hook qui agit après une action ne peut pas l'annuler. Le fichier est déjà modifié, la commande déjà lancée. Pour empêcher, il faut agir avant.

Avant de commencer

Il te faut Claude Code, installé et connecté. Il tourne sous macOS 13 ou plus récent, Windows 10 (version 1809) ou plus récent, Ubuntu 20.04, Debian 10 ou Alpine 3.19 et plus récents, avec 4 Go de mémoire vive. Il demande un abonnement Pro, Max, Team ou Enterprise, ou un compte Console : l'offre gratuite de claude.ai ne donne pas accès à Claude Code.

Pas encore installé ? La page d'installation officielle donne la commande de ton système, et la formation Claude Code : bien démarrer t'accompagne pas à pas. Vérifie ensuite dans un terminal :

claude --version

Ce premier hook ne demande rien d'autre. Les scripts des chapitres suivants sont écrits pour Node.js, en version LTS : la 24 au 19 octobre 2026. Vérifie avec node --version. Sous Windows, installe aussi Git for Windows : Claude Code s'en sert pour son outil Bash, et sans lui, tes hooks écrits en ligne de commande passent par PowerShell.

Ton premier hook, en deux minutes

Commence par le plus simple : être prévenu quand Claude a besoin de toi. Voici l'exemple Windows de la documentation officielle, avec un message en français. Ouvre ton fichier de réglages personnel, ~/.claude/settings.json. Sous Windows, c'est C:\Users\<ton-nom>\.claude\settings.json.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code a besoin de toi', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

Si le fichier contient déjà des réglages, ajoute seulement la clé hooks à côté des autres. C'est du JSON strict : pas de commentaire, pas de virgule après le dernier élément.

Sur macOS, la documentation utilise cette commande à la place :

osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'

Et sur Linux :

notify-send 'Claude Code' 'Claude Code needs your attention'

Lance d'abord la commande seule dans un terminal. Sur macOS, la notification passe par l'app Éditeur de script (Script Editor) : si elle n'a pas le droit d'afficher des notifications, rien ne s'affiche, et macOS ne te le demande pas. Sur Linux, notify-send a besoin d'un service de notifications de bureau, absent d'un serveur, d'une session SSH et de la plupart des conteneurs.

Pour vérifier, tape /hooks dans Claude Code. La liste de tes hooks s'affiche, rangée par événement : le tien apparaît sous Notification.

Pour tester, il faut une demande d'accord. Depuis la version 2.1.283, une session démarre en mode auto, qui en affiche rarement. Appuie donc sur Shift+Tab jusqu'à ce que la barre d'état affiche « manual mode on ». Demande ensuite à Claude une action qui demande ton accord, et passe sur une autre fenêtre. Après quelques secondes, la boîte apparaît.

Consigne ou hook : comment choisir

Tout ne doit pas devenir un hook. La documentation fait la part des choses, et je fais pareil :

• CLAUDE.md pour ce qui guide le comportement : conventions de code, architecture, façon d'écrire.
• Un hook ou un réglage pour ce qui doit être appliqué à chaque fois : bloquer, formater, tester, prévenir.

Mon test est simple. Si un petit programme peut vérifier la règle sans réfléchir, c'est un hook. Si elle demande du jugement, c'est une consigne.

Ce que la suite t'apporte

Dans la leçon suivante, j'ouvre mes vrais garde-fous. Le premier exige des faits avant la première modification de chaque fichier. Le deuxième empêche Claude d'affaiblir la configuration du linter pour faire passer un contrôle. Et je te montre ce que j'ai découvert en vérifiant la protection de mes propres fichiers .env.

Ensuite, la formation passe à l'écriture :

• Chapitre 2 : les événements disponibles, le fichier settings.json et sa portée, puis les deux façons de dire non, le code de sortie 2 et la réponse JSON. Tu repars avec le hook qui protège tes fichiers .env.
• Chapitre 3 : trois hooks du quotidien, prêts à copier et testés sous Windows. Prettier après chaque modification, tests lancés avant que Claude s'arrête, notification quand il t'attend. Puis la sécurité : un hook exécute du code sur ta machine, avec tes droits.