Guide · IA & agents
Hooks Claude Code : 7 exemples sûrs et prêts à copier
Configurez 7 hooks Claude Code pour formater, tester, protéger les secrets et demander une validation, avec un contrôle concret pour chaque exemple.

Les hooks Claude Code lancent une commande à un moment précis de la session : avant un outil, après une modification, au démarrage ou quand Claude réclame votre attention. Ils conviennent aux contrôles déterministes, comme refuser l’écriture d’un fichier de secrets ou vérifier un JSON. Ce tutoriel installe sept recettes locales, sans service distant et sans commande de suppression.
En bref. Vous allez ajouter un seul script Python, puis sept configurations indépendantes dans
.claude/settings.json. Chaque hook a un test positif et un résultat observable. Comptez 45 à 60 minutes. Les exemples restent locaux, utilisent la bibliothèque standard de Python et peuvent être désactivés depuis/hooks.
Prérequis
- Claude Code installé et fonctionnel dans un dépôt de démonstration.
- Python 3 disponible avec
python3 --version. - Un éditeur capable de valider du JSON.
- Un dépôt sans données sensibles pour les premiers essais.
- Une copie du contenu actuel de
.claude/settings.jsonavant toute fusion manuelle.
Les exemples ciblent macOS et Linux. Sous Windows, utilisez py si la commande python3 n’existe pas et adaptez les guillemets au shell choisi. Commencez par le guide d’installation de Claude Code si la commande n’est pas encore disponible. Pour replacer les hooks parmi les autres briques de l’outil, consultez le glossaire agent, skill et prompt.
Étape 1 : comprendre le schéma d’un hook
Dans .claude/settings.json, la clé hooks contient un tableau par événement. Un groupe peut avoir un matcher, puis un tableau hooks avec les commandes à exécuter. La documentation officielle distingue notamment :
| Événement | Moment d’exécution | Usage dans ce tutoriel |
|---|---|---|
PreToolUse | Avant l’appel d’un outil | Refuser ou soumettre une action à validation |
PostToolUse | Après la réussite d’un outil | Formater, valider, lancer des tests |
Notification | Quand Claude Code émet une notification | Produire un signal local |
SessionStart | Au démarrage, à la reprise ou après compaction | Réinjecter un rappel court |
Le matcher filtre le nom de l’outil ou le sous-type de l’événement. Edit|Write vise les outils d’écriture. Pour un hook SessionStart, compact vise le redémarrage logique qui suit une compaction. Une commande reçoit sur son entrée standard un objet JSON avec des champs communs, dont hook_event_name, session_id et cwd, puis des champs propres à l’événement. PreToolUse et PostToolUse reçoivent aussi tool_name et tool_input.
Placez les hooks partagés dans .claude/settings.json. Les préférences personnelles vont plutôt dans .claude/settings.local.json, tandis que ~/.claude/settings.json s’applique à vos projets locaux. Après une modification, ouvrez /hooks pour vérifier la source et l’événement chargés.
Un hook PreToolUse peut renvoyer une décision JSON structurée. deny annule l’outil, ask conserve une demande de validation humaine et allow évite l’invite normale sans contourner les règles de refus administrées. Pour les contrôles simples, une sortie de code 2 avec un message sur stderr peut aussi bloquer certains événements, mais son effet varie selon l’événement. Les exemples de décision utilisent donc le schéma structuré documenté.
Étape 2 : créer le script commun
Créez le dossier, puis le fichier .claude/hooks/safe_hooks.py :
mkdir -p .claude/hooks
Copiez ce script. Il lit l’objet transmis par Claude Code, refuse les chemins hors du dépôt et ne contacte aucun service externe.
#!/usr/bin/env python3
import ast
import json
import os
import subprocess
import sys
from pathlib import Path
def read_event():
return json.load(sys.stdin)
def project_and_file(event):
root = Path(os.environ.get("CLAUDE_PROJECT_DIR", event.get("cwd", "."))).resolve()
raw = event.get("tool_input", {}).get("file_path")
if not raw:
return root, None
target = Path(raw)
if not target.is_absolute():
target = root / target
target = target.resolve()
try:
target.relative_to(root)
except ValueError:
return root, None
return root, target
def decision(value, reason):
print(json.dumps({
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": value,
"permissionDecisionReason": reason,
}
}))
def protect_secrets(event):
raw = event.get("tool_input", {}).get("file_path")
_, target = project_and_file(event)
if raw and target is None:
decision("deny", "Chemin situé hors du dépôt : écriture refusée par ce hook.")
return
if target is None:
return
protected_names = {".env", ".env.local", ".env.production", "credentials.json"}
protected_suffixes = {".pem", ".key", ".p12"}
if target.name in protected_names or target.suffix.lower() in protected_suffixes:
decision("deny", f"Fichier sensible protégé par le hook : {target.name}")
def confirm_publish(event):
command = event.get("tool_input", {}).get("command", "")
markers = ("npm publish", "pnpm publish", "vercel --prod", "git push")
if any(marker in command for marker in markers):
decision("ask", "Publication ou envoi distant : validation humaine requise.")
def format_markdown(event):
_, target = project_and_file(event)
if target is None or target.suffix.lower() not in {".md", ".mdx"} or not target.is_file():
return
original = target.read_text(encoding="utf-8")
formatted = "\n".join(line.rstrip() for line in original.splitlines()) + "\n"
if formatted != original:
target.write_text(formatted, encoding="utf-8")
print(f"Espaces de fin de ligne retirés : {target}")
def validate_json(event):
_, target = project_and_file(event)
if target is None or target.suffix.lower() != ".json" or not target.is_file():
return
try:
json.loads(target.read_text(encoding="utf-8"))
except json.JSONDecodeError as error:
print(f"JSON invalide dans {target.name}, ligne {error.lineno}: {error.msg}", file=sys.stderr)
raise SystemExit(2)
def run_python_tests(event):
root, target = project_and_file(event)
if target is None or target.suffix.lower() != ".py" or not (root / "tests").is_dir():
return
try:
ast.parse(target.read_text(encoding="utf-8"), filename=str(target))
except SyntaxError as error:
print(f"Python invalide dans {target.name}, ligne {error.lineno}: {error.msg}", file=sys.stderr)
raise SystemExit(2)
result = subprocess.run(
[sys.executable, "-m", "unittest", "discover", "-s", "tests"],
cwd=root,
check=False,
)
raise SystemExit(0 if result.returncode == 0 else 2)
def notify(_event):
sys.stderr.write("\aClaude Code demande votre attention.\n")
def session_context(_event):
print("Rappel après compaction : relire CLAUDE.md, garder le périmètre et exécuter les contrôles du dépôt.")
MODES = {
"protect-secrets": protect_secrets,
"confirm-publish": confirm_publish,
"format-markdown": format_markdown,
"validate-json": validate_json,
"run-python-tests": run_python_tests,
"notify": notify,
"session-context": session_context,
}
if __name__ == "__main__":
if len(sys.argv) != 2 or sys.argv[1] not in MODES:
raise SystemExit("Mode de hook inconnu")
MODES[sys.argv[1]](read_event())
Le mode run-python-tests utilise unittest, car il est inclus dans Python. Si votre dépôt emploie une autre commande de test, remplacez seulement la liste passée à subprocess.run après l’avoir vérifiée dans les instructions du projet. Le guide des permissions Claude Code complète cette approche pour les règles qui doivent rester actives même si les hooks sont désactivés.
Étape 3 : hook 1, signaler une demande d’attention
Ce hook émet un bip terminal et un message local lorsque Claude Code produit une notification. Il ne transmet ni prompt ni chemin.
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" notify",
"timeout": 10
}
]
}
]
}
}
Test : activez le mode manuel avec Shift+Tab, demandez une action qui exige une permission, puis quittez la fenêtre du terminal. Le terminal doit émettre un signal et afficher « Claude Code demande votre attention ». Si votre terminal ignore le caractère d’alerte, le message reste visible ; remplacez ensuite cette fonction par le système de notification local de votre OS, pas par un webhook distant contenant la conversation.
Étape 4 : hook 2, nettoyer le Markdown après écriture
Cette recette retire uniquement les espaces en fin de ligne dans les fichiers .md et .mdx. Elle ignore les autres extensions et les chemins hors du dépôt.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" format-markdown",
"timeout": 10
}
]
}
]
}
}
Test : créez notes/hook-test.md avec une ligne terminée par deux espaces, puis demandez à Claude d’ajouter une seconde ligne. Affichez les caractères invisibles dans l’éditeur : les espaces finaux doivent avoir disparu et le fichier doit finir par un saut de ligne. Faites ce premier essai sur un fichier jetable, car un formateur automatique modifie réellement le contenu.
Étape 5 : hook 3, vérifier chaque JSON modifié
Le contrôle suivant analyse le fichier avec la bibliothèque standard. Il ne reformate pas le JSON et n’essaie pas de le réparer silencieusement.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" validate-json",
"timeout": 10
}
]
}
]
}
}
Test : dans un fichier de démonstration, demandez l’ajout volontaire d’une virgule finale invalide. Le hook doit signaler le nom du fichier, la ligne et l’erreur. L’écriture a déjà eu lieu, car PostToolUse intervient après l’outil : corrigez le fichier ou revenez sur ce changement. Un hook de validation n’est pas une transaction qui annule automatiquement l’édition.
Étape 6 : hook 4, lancer les tests Python ciblés
Après l’écriture d’un fichier Python, ce hook vérifie sa syntaxe puis lance la suite unittest si un dossier tests/ existe. Il ne télécharge rien et ne crée pas de dépendance.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" run-python-tests",
"timeout": 120,
"statusMessage": "Tests Python locaux"
}
]
}
]
}
}
Test : ajoutez dans une petite fonction une modification qui conserve le comportement attendu. Le hook doit terminer avec la sortie unittest réussie. Introduisez ensuite une valeur de retour incorrecte dans cette fonction de démonstration : les tests doivent échouer et Claude doit recevoir l’échec. Remettez aussitôt le fichier dans son état initial.
Ne lancez pas toute une suite lente après chaque caractère. PostToolUse s’exécute après un appel d’outil, mais plusieurs appels peuvent se succéder. Pour un gros dépôt, remplacez la commande par un test lié au fichier ou gardez les tests complets pour la CI.
Étape 7 : hook 5, protéger les fichiers de secrets
Ce PreToolUse examine le chemin avant Edit ou Write. Il refuse quelques noms et extensions sensibles, sans lire leur contenu.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" protect-secrets",
"timeout": 10
}
]
}
]
}
}
Test : créez un fichier .env factice sans secret, puis demandez à Claude d’y ajouter un commentaire. L’outil doit être annulé et le motif « Fichier sensible protégé » doit revenir dans la session. Vérifiez que le fichier n’a pas changé. Adaptez la liste à vos conventions, par exemple un dossier de certificats ou un nom de coffre local.
Étape 8 : hook 6, demander une validation avant publication
Cette recette ne bloque pas définitivement les commandes repérées. Elle renvoie ask, afin que Claude Code présente sa demande de permission normale. Les marqueurs couvrent quatre actions d’envoi ou de publication courantes.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" confirm-publish",
"timeout": 10
}
]
}
]
}
}
Test : sans exécuter de publication, envoyez un événement synthétique au script :
printf '%s' '{"cwd":".","tool_input":{"command":"npm publish --dry-run"}}' | python3 .claude/hooks/safe_hooks.py confirm-publish
La sortie doit contenir "permissionDecision": "ask". Refaites le test avec python3 --version : aucune sortie n’est attendue. Cette comparaison montre que le hook ne transforme pas toutes les commandes Bash en demande d’autorisation.
Étape 9 : hook 7, rappeler le contexte après compaction
Une compaction résume la conversation et peut perdre un détail opérationnel. SessionStart avec le matcher compact peut réinjecter un rappel bref. Les conventions stables restent toutefois dans CLAUDE.md, pas dans une longue commande echo.
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{
"type": "command",
"command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/safe_hooks.py\" session-context",
"timeout": 10
}
]
}
]
}
}
Test : lancez /compact dans un dépôt de démonstration. Au retour de la session, demandez à Claude de rappeler les contraintes actives. Le texte sur CLAUDE.md, le périmètre et les contrôles doit être présent dans le contexte. Pour une règle durable et détaillée, utilisez plutôt le guide pour écrire un bon CLAUDE.md.
Étape 10 : fusionner et contrôler la configuration
Les sept blocs ci-dessus sont indépendants afin que chaque recette soit copiable. Dans le vrai fichier, ne créez qu’une seule clé hooks. Regroupez les groupes partageant PreToolUse ou PostToolUse dans le même tableau. Ne remplacez pas les hooks existants sans les avoir lus.
Validez d’abord le JSON avec Python :
python3 -m json.tool .claude/settings.json >/dev/null
Ouvrez ensuite /hooks et vérifiez que chaque événement apparaît sous la source Project. Déclenchez les essais un par un. Si une recette échoue, lancez Claude Code avec claude --debug ou utilisez /debug pendant la session. La référence officielle indique aussi que les modifications externes de hooks pendant une session peuvent produire un avertissement : rechargez ou redémarrez plutôt que d’interpréter un ancien résultat.
Pourquoi un hook n’est pas une barrière de sécurité
Un hook est du code local exécuté avec les droits du processus Claude Code. Il peut contenir un bug, être désactivé avec disableAllHooks, ne pas être chargé dans un environnement distant ou être modifié avec les réglages du projet. Un matcher fondé sur une chaîne de commande peut aussi rater une autre syntaxe qui produit le même effet.
Gardez donc plusieurs couches : permissions Claude Code restrictives, environnement isolé, secrets hors du dépôt, règles d’organisation, revue humaine et CI. Le hook qui protège .env réduit les erreurs ordinaires ; il ne remplace ni les permissions du système ni un gestionnaire de secrets. Le hook de tests donne un retour rapide ; il ne prouve pas que tous les comportements sont corrects. Pour un agent outillé, le guide du moindre privilège détaille cette séparation.
Relisez aussi tout hook tiers avant activation. La documentation officielle avertit que les hooks exécutent automatiquement des commandes avec les identifiants de l’utilisateur. Contrôlez les guillemets, les chemins, les entrées non fiables, les accès réseau et les écritures. Préférez un script versionné à une longue commande shell difficile à auditer.

Erreurs fréquentes
Le hook n’apparaît pas dans /hooks
Le JSON est peut-être invalide ou la clé a été placée au mauvais niveau. Passez le fichier dans python3 -m json.tool, puis vérifiez que l’événement se trouve sous l’unique objet hooks. Confirmez enfin que vous avez ouvert Claude Code depuis le projet attendu.
Le hook se lance sur tous les outils
Un matcher vide correspond largement, ce qui convient parfois à Notification mais rarement à PostToolUse. Utilisez Edit|Write pour les écritures et gardez le contrôle de l’extension dans le script. Ne supposez pas que le matcher reçoit un chemin : pour ces événements, il filtre d’abord le nom de l’outil.
Le script casse avec un chemin contenant des espaces
Entourez le chemin complet de guillemets dans command, comme dans les sept exemples. Dans le script, utilisez pathlib.Path et les arguments de subprocess.run sous forme de liste. Évitez de reconstruire une commande shell à partir de tool_input.
Le contrôle arrive après la modification
C’est le comportement normal de PostToolUse. Employez PreToolUse pour décider avant l’action, puis PostToolUse pour formater ou vérifier le résultat. Un test qui échoue après une écriture signale un problème, mais ne restaure pas le fichier.
Claude tourne en boucle après un blocage
Le message de refus doit expliquer la solution autorisée. Si vous utilisez plus tard un hook Stop, vérifiez le champ stop_hook_active avant de demander une nouvelle action ; la documentation le prévoit pour éviter qu’un hook d’arrêt se relance sans fin. Les exemples de ce tutoriel n’ajoutent pas de hook Stop.
Récapitulatif
Vous disposez de sept hooks contrôlés : notification locale, nettoyage Markdown, validation JSON, tests Python, protection de fichiers sensibles, validation avant publication et rappel après compaction. Installez-les séparément, observez chaque résultat, puis fusionnez les tableaux dans un seul .claude/settings.json.
Gardez le script court et versionné. Toute automatisation qui écrit dans les fichiers doit être réversible, toute décision de refus doit donner un motif, et toute action distante doit rester soumise aux permissions et à une validation humaine.
Questions fréquentes
Où mettre les hooks Claude Code ?
Utilisez .claude/settings.json pour un hook partagé par le projet, .claude/settings.local.json pour un réglage personnel lié au projet et ~/.claude/settings.json pour vos projets locaux. Les sessions cloud ne lisent pas automatiquement le fichier utilisateur de votre machine.
Quelle différence entre PreToolUse et PostToolUse ?
PreToolUse intervient avant l’outil et peut refuser, demander ou autoriser l’appel selon le schéma de décision. PostToolUse intervient après une réussite ; il convient au formatage et aux validations, mais ne revient pas automatiquement sur l’action déjà faite.
Comment tester un hook sans lancer l’action réelle ?
Envoyez un petit objet JSON au script avec printf, comme dans le test du hook de publication. Cette méthode vérifie la logique du script sans demander à Claude d’exécuter la commande repérée. Testez ensuite le branchement de l’événement dans un dépôt jetable.
Peut-on désactiver tous les hooks ?
Oui, disableAllHooks permet de désactiver les hooks configurables depuis les réglages ordinaires, et /hooks fournit une interface de gestion. Les hooks imposés par une politique administrée peuvent suivre des règles différentes. Ne faites donc pas d’un hook votre unique contrôle de sécurité.
Faut-il utiliser exit 2 ou une décision JSON ?
Une sortie 2 est pratique pour un blocage simple, mais son traitement dépend de l’événement. Une décision JSON avec hookSpecificOutput est plus explicite pour PreToolUse et permet deny, ask ou allow. Ne mélangez pas les deux mécanismes dans la même exécution.
Sources
- Anthropic, Hooks reference, événements, schéma de configuration, entrées, sorties, codes de retour et considérations de sécurité, consulté le 4 novembre 2026.
- Anthropic, Automate actions with hooks, configuration dans
settings.json, matchers, exemples, tests et débogage, consulté le 4 novembre 2026.