Déclencheurs et notifications

1Déclencher sur un événement de session

Un hook est une commande lancée par le harnais, pas par le modèle. C'est ce qui le rend fiable : il n'y a rien à oublier.

La liste des événements est longue. Ceux qui servent le plus souvent :

La configuration va dans .claude/settings.json pour le projet, ~/.claude/settings.json pour tous tes projets, ou hooks/hooks.json si tu la distribues dans un plugin.

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

Le contexte arrive en JSON sur l'entrée standard : jq en extrait ce dont tu as besoin. Les codes de sortie ont un sens précis : 0 réussit, 2 est une erreur bloquante dont la sortie d'erreur est transmise au modèle, tout autre code est une erreur non bloquante qui laisse l'action se poursuivre.

2Déclencher sur un fichier modifié

Deux approches, selon que la surveillance doit vivre pendant une session ou en permanence.

Pendant une session, l'événement FileChanged se déclenche quand un fichier surveillé change sur le disque. C'est le cas typique du fichier de traduction ou du schéma que quelqu'un d'autre modifie pendant que tu travailles.

En permanence, il faut un surveillant externe qui appelle Claude Code en mode non interactif. Des outils comme entr, watchexec ou inotifywait font ça, et ils sont indépendants de Claude Code.

Deux précautions valables pour tous : exclus les dossiers générés de la surveillance, sinon la sortie de l'agent redéclenche l'agent. Et pose un délai d'attente avant l'exécution, sinon une sauvegarde qui écrit trois fichiers déclenche trois exécutions.

3Déclencher à l'heure

En local, cron suffit. Pour quelque chose de partagé avec l'équipe, GitHub Actions accepte une planification.

on:
  schedule:
    - cron: "0 7 * * 1"

Trois limites à connaître : l'intervalle minimum est de cinq minutes, les horaires sont exprimés en UTC, et les exécutions planifiées peuvent être retardées en période de charge. Pour un rapport hebdomadaire, aucune des trois n'a d'importance. Pour un déclenchement à la minute près, ce n'est pas le bon outil.

Le corps de la tâche, lui, est un appel non interactif :

claude -p "$(cat prompt-rapport.txt)" > rapport.md

4Déclencher depuis l'extérieur

Un webhook, ici, n'a rien de spécifique à Claude Code : c'est un petit serveur HTTP à toi qui reçoit une requête et lance la commande. Le point d'attention n'est pas le montage, c'est la sécurité.

Trois règles :

• Vérifie la signature de l'appel entrant, avec le secret partagé fourni par le service émetteur. Un point d'entrée non authentifié sur internet est trouvé en quelques heures.
• N'injecte jamais le corps de la requête dans la commande shell. Écris-le dans un fichier, et passe le chemin au prompt.
• Traite le contenu reçu comme du texte hostile. Il vient de l'extérieur, il peut contenir des instructions destinées au modèle.

5Poser les garde-fous avant de brancher

Un agent déclenché automatiquement n'a personne devant l'écran. Ces drapeaux ne sont pas optionnels.

claude -p "$(cat prompt.txt)" \
  --max-turns 12 \
  --max-budget-usd 1.00 \
  --allowedTools "Read" "Grep" "Glob" \
  --output-format json \
  > resultat.json

--max-turns limite le nombre de tours agentiques, --max-budget-usd fixe un plafond de dépense avant arrêt, et --allowedTools restreint ce qui s'exécute sans demander. Le --output-format json rend la sortie exploitable par le script qui suit, au lieu d'un texte à analyser.

Le premier réflexe à avoir : commence en lecture seule. Un agent déclenché qui ne peut que lire et écrire un rapport ne peut pas faire de dégât, et tu verras en une semaine s'il fait ce que tu attends.

6Être prévenu du résultat

Le plus simple d'abord. Un hook Stop qui fait du bruit à la fin d'une tâche longue :

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "printf '\\a'" } ] }
    ]
  }
}

Sur macOS, osascript -e 'display notification "Termine"' donne une vraie notification système.

Pour une notification qui parte ailleurs que sur ta machine, un hook peut aussi être de type http : il envoie une requête POST avec le contexte en JSON dans le corps. Sinon, un curl vers l'URL d'intégration de ta messagerie d'équipe fait le travail depuis un hook de type command.

Et prévois le cas de l'échec. Un agent planifié qui plante silencieusement passe inaperçu pendant des semaines : tu crois qu'il n'y a rien à signaler alors qu'il ne tourne plus. Fais envoyer une notification distincte quand le code de sortie n'est pas zéro.