N-Gage Formation Claude

Claude Code

Hooks Claude Code (settings.json)

Statut : stable Plan minimum : Pro Démo : 8-15 min Vérifié le : 2026-05-17

Source officielle : https://code.claude.com/docs/en/hooks

Hooks Claude Code (settings.json)

TL;DR

Les hooks sont des commandes shell que Claude Code déclenche automatiquement à des moments précis de son cycle de vie : avant un appel d'outil, après une édition, à la soumission d'un prompt, à la fin d'un tour. Vous les déclarez dans un fichier JSON (settings.json), ils s'exécutent dans votre terminal local avec vos droits, et peuvent autoriser, bloquer ou enrichir l'action en cours. C'est la mécanique qui transforme Claude Code d'un simple assistant en agent intégré à votre environnement (formatage, notifications, audit, garde-fous). Les hooks classiques sont stables ; les hooks de type agent restent expérimentaux et à manipuler avec prudence.

Pour qui c'est utile

Les hooks sont une fonctionnalité avancée. Ils s'adressent à des utilisateurs qui sont à l'aise avec un terminal, un fichier JSON et une commande shell. Profils types qui en tirent le maximum :

  • Développeurs solo qui veulent automatiser un formatage (prettier, black, gofmt) après chaque édition, lancer les tests à chaque écriture, ou être notifiés quand un tour long se termine
  • Tech leads et CTO qui veulent imposer des règles communes à toute l'équipe via le settings.json versionné dans le dépôt (lint obligatoire, blocage de commandes destructrices, hook d'audit)
  • Sysadmins et ingénieurs plateforme qui veulent loguer ce que Claude Code fait sur leurs machines (audit, conformité, traçabilité), pousser ces logs vers un outil interne, ou interdire certaines actions
  • Power users en R&D qui veulent connecter Claude Code à leur propre stack (envoi de notifications Slack, déclenchement d'un workflow n8n, écriture dans une base de données)

Si vous n'avez jamais ouvert un terminal et que vous n'êtes pas à l'aise avec un fichier JSON, restez sur les Skills et les Projects. Les hooks attendront.

Comprendre les hooks Claude Code (la mécanique sous le capot)

Un hook, c'est trois choses combinées :

Un évènement déclencheur, choisi dans une liste fournie par Claude Code (plus de 30 évènements disponibles). Les plus utiles au quotidien :

  • PreToolUse : juste avant l'exécution d'un outil (Bash, Edit, Write, Read, etc.). C'est là qu'on bloque une action si on ne veut pas la laisser passer.
  • PostToolUse : juste après l'exécution d'un outil. C'est là qu'on enchaîne (formater le code après une édition, relancer les tests après une écriture).
  • UserPromptSubmit : à chaque fois que vous envoyez un message à Claude Code. Utile pour enrichir le contexte ou loguer la requête.
  • Stop : quand Claude Code termine son tour de parole. Idéal pour une notification de fin de tâche longue.
  • SessionStart et SessionEnd : ouverture et fermeture d'une session Claude Code. Utile pour préparer un environnement ou archiver des logs.

Une commande shell, exécutée localement à chaque fois que l'évènement se déclenche. Elle reçoit en entrée (stdin) un JSON décrivant l'évènement : nom de l'outil concerné, paramètres, chemin du projet, etc. Elle peut écrire sur stdout (ce qui sera lu par Claude Code) ou stderr (pour vos logs).

Un fichier de configuration JSON, où vous déclarez le tout :

  • ~/.claude/settings.json : réglages personnels, valables pour tous vos projets (notifications macOS, alias perso)
  • .claude/settings.json à la racine d'un projet : réglages versionnés dans le dépôt git, partagés avec l'équipe (lint, format, garde-fous)
  • .claude/settings.local.json à la racine d'un projet : réglages propres au projet mais non commités (chemins locaux, secrets de dev)

Point important sur le blocage : un hook PreToolUse peut empêcher Claude Code d'exécuter une action en sortant avec le code retour 2. Les autres codes non zéro sont traités comme des erreurs non bloquantes (logguées mais ignorées). Cette convention est spécifique aux hooks de Claude Code, elle est documentée mais souvent oubliée.

Les hooks de type agent (qui déclenchent un sous-agent Claude au lieu d'une commande shell) sont marqués expérimentaux dans la documentation officielle : signature et comportement peuvent changer. À éviter en production tant que le statut n'a pas évolué.

Quand un hook est pertinent vs un Skill vs un prompt direct

Trois mécanismes différents, à ne pas confondre :

  • Un hook s'exécute automatiquement et systématiquement à un évènement précis. Il agit dans votre environnement (fichiers, processus, réseau) avec vos droits. C'est le bon choix pour une règle technique non négociable (toujours formater, jamais d'effacement récursif, toujours logguer).
  • Un Skill s'active quand Claude juge que c'est pertinent à partir d'une description. Il agit dans la conversation (rédige, structure, oriente). C'est le bon choix pour un livrable récurrent ou une expertise métier.
  • Un prompt direct s'applique uniquement à la conversation en cours. C'est le bon choix pour un besoin ponctuel.

Règle pratique : si la règle doit s'appliquer à chaque fois sans dépendre du jugement de Claude (audit, sécurité, format), c'est un hook. Si elle dépend du contexte et qu'on accepte de la rater de temps en temps, c'est un Skill ou un prompt.

Pas à pas détaillé

Ouvrir le bon fichier de configuration

  1. Décidez du niveau de portée. Pour tester, commencez par le niveau personnel : ~/.claude/settings.json.
  2. Vérifiez si le fichier existe : ls -la ~/.claude/settings.json. S'il n'existe pas, créez-le avec un objet JSON vide {}.
  3. Ouvrez-le dans votre éditeur préféré. Le fichier doit rester un JSON valide : la moindre virgule en trop fait que tout le fichier est ignoré sans message clair.

Déclarer un premier hook simple

  1. Ajoutez une section hooks à la racine du JSON. Exemple minimal qui logge chaque fin de tour :

json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "echo \"$(date) - Claude a terminé un tour\" >> ~/claude-stop.log" } ] } ] } }

  1. Sauvegardez le fichier. Vérifiez la validité JSON avec cat ~/.claude/settings.json | jq . (si jq est installé) ou n'importe quel linter en ligne.

Tester le hook

  1. Relancez Claude Code (quittez la session en cours puis rouvrez-en une nouvelle, les hooks ne sont rechargés qu'au démarrage).
  2. Posez une question simple à Claude pour déclencher un tour de réponse.
  3. Vérifiez dans un autre terminal : tail ~/claude-stop.log. Une nouvelle ligne doit apparaître. Si rien ne s'écrit, regardez la section pièges plus bas.

Ajouter un matcher pour cibler précisément

  1. Pour les évènements PreToolUse et PostToolUse, vous pouvez filtrer par nom d'outil grâce au champ matcher. Exemple qui formate uniquement après une édition de fichier :

json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "prettier --write \"$CLAUDE_PROJECT_DIR\" 2>/dev/null || true" } ] } ] } }

  1. Le | dans le matcher fait un OU logique. Ici le hook se déclenche après Edit OU après Write. La variable $CLAUDE_PROJECT_DIR est fournie par Claude Code.

Cas d'usage avec exemples concrets

Cas 1, auto-format après écriture (développeur solo) : un hook PostToolUse sur Edit|Write qui lance prettier --write ou black sur le projet. Bénéfice : le code reste propre sans avoir à le demander à chaque fois. À mettre dans .claude/settings.json pour l'imposer à toute l'équipe.

Cas 2, notification système sur action sensible (sysadmin) : un hook PreToolUse qui détecte les appels Bash et envoie une notification macOS avec la commande sur le point d'être exécutée :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude lance une commande\" with title \"Claude Code\"'" }
        ]
      }
    ]
  }
}

Cas 3, log d'audit centralisé (tech lead en équipe) : un hook PostToolUse qui envoie chaque action de Claude (outil utilisé, fichier touché, horodatage) vers un endpoint HTTP interne, alimenté ensuite dans un dashboard. Permet de répondre à la question « qu'est-ce que Claude a modifié hier ? » sans dépouiller les transcripts.

Cas 4, blocage d'une commande dangereuse (sécurité) : un hook PreToolUse sur Bash qui inspecte la commande et sort en code 2 si elle contient rm -rf ou dd if=. Garde-fou simple mais efficace pour empêcher une frappe malheureuse sur un environnement sensible. Exemple de cœur de hook (script shell) :

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
if echo "$cmd" | grep -qE 'rm -rf|dd if='; then
  echo "Commande bloquée par hook de sécurité" >&2
  exit 2
fi
exit 0

À retenir

  • Un hook reçoit en stdin un JSON décrivant l'évènement (outil, paramètres, chemin projet). Il peut tracer, transformer ou bloquer.
  • Pour bloquer depuis un PreToolUse, sortez en code 2. Le code 1 est traité comme une erreur non bloquante, ce qui peut prêter à confusion.
  • Le settings.json est commun aux différentes surfaces de Claude Code (CLI, extensions IDE, environnements distants) : un même hook s'applique partout où vous utilisez Claude Code avec ce profil.
  • Trois niveaux de portée à bien choisir : personnel global, projet partagé via git, projet local non commité. Mélanger les trois est la source numéro un de bugs et de surprises.
  • Les hooks de type agent sont expérimentaux : signature et comportement peuvent changer. Évitez-les en production.

Pièges à éviter

  • JSON invalide : une virgule en trop et tout le settings.json est ignoré sans message clair. Validez le fichier avec jq . avant de relancer.
  • Hooks agent instables : marqués expérimentaux dans la doc officielle. Restez sur les hooks command tant que ce n'est pas stabilisé.
  • Blocage involontaire : un hook qui sort en code 2 par accident (commande absente, erreur de parsing) va bloquer Claude Code de façon mystérieuse. Testez vos hooks avec des entrées variées avant de les imposer à toute l'équipe.
  • Performance : un hook qui prend 3 secondes à chaque PostToolUse rallonge chaque interaction de 3 secondes. Gardez les hooks courts (< 200 ms) ou exécutez-les en arrière-plan (commande &).
  • Hook qui boucle : un PostToolUse qui modifie un fichier peut redéclencher Claude, qui redéclenche le hook. Ciblez bien le matcher et évitez les hooks qui se mordent la queue.
  • Sécurité : un hook est un script local qui s'exécute avec vos droits. Ne copiez jamais un hook trouvé en ligne sans le lire. Préférez la forme command + args à une longue ligne shell pour éviter l'injection.
  • Confusion entre niveaux : un hook dans .claude/settings.json est partagé avec toute l'équipe via git. Si c'est un réglage personnel (notif macOS, chemin local), mettez-le dans ~/.claude/settings.json ou .claude/settings.local.json.
  • Debugging difficile : sans set -e ni log, une erreur passe inaperçue. Ajoutez un echo ou un fichier de log le temps de la mise au point, et regardez le code retour avec echo $?.

Exercice 1 minute

Ajoutez ce hook minimal dans ~/.claude/settings.json :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "echo \"$(date) Claude a terminé\" >> ~/claude-stop.log" }
        ]
      }
    ]
  }
}

Relancez Claude Code, posez une question simple, puis dans un autre terminal lancez tail ~/claude-stop.log. Si une ligne apparaît, votre premier hook fonctionne. Vous pouvez maintenant ajouter des règles plus utiles (auto-format, notifications, garde-fous).

Variantes par plan

  • Free : Claude Code n'est pas accessible.
  • Pro : accès complet aux hooks personnels et projet.
  • Team : le .claude/settings.json versionné permet de diffuser des hooks de qualité (formatage, lint, garde-fous) à toute l'équipe via git.
  • Enterprise : managed settings centralisés au niveau de l'organisation, et option allowManagedHooksOnly pour interdire les hooks définis par les utilisateurs hors cadre validé.

Liens internes