Chapter 3 · Chapitre 3 · Écrire sa première configuration
3.4 Vérifier et dépanner sa configuration
Follow this course in your space: your progress is saved, and the community answers your questions.
Follow for freeTon hook ne fait rien ? Voici la méthode, dans l'ordre. Elle reprend la section de dépannage de la documentation officielle.
1. Est-il chargé ?
Tape /hooks. Ce menu liste tous les hooks configurés, classés par événement, en lecture seule. S'il n'y est pas :
- vérifie que le JSON est valide (pas de virgule finale, pas de commentaire) ;
- vérifie l'emplacement :
.claude/settings.jsonpour un projet,~/.claude/settings.jsonpour tous ; - d'après la doc, les modifications sont normalement prises en compte automatiquement ; si rien n'apparaît après quelques secondes, redémarre la session.
2. As-tu accepté la confiance du dossier ?
En session interactive, la doc indique que Claude Code retient les hooks de tous les fichiers de réglages, y compris ton ~/.claude/settings.json, tant que tu n'as pas accepté la boîte de dialogue de confiance du dossier. Si tu l'as refusée, aucun hook ne tourne.
3. Se déclenche-t-il au bon moment ?
- Le matcher correspond-il exactement au nom de l'outil, majuscules comprises ?
- As-tu choisi le bon événement (avant ou après) ?
- Un
ifsur un événement non lié aux outils empêche toute exécution.
4. La commande fonctionne-t-elle seule ?
Lance-la toi-même en lui envoyant un faux événement (méthode détaillée en leçon 4.4). Si elle échoue seule, elle échouera aussi dans Claude Code.
5. Que s'est-il passé ?
La doc recommande d'ouvrir la vue détaillée de la conversation avec Ctrl+O. Un succès n'affiche rien ; un blocage affiche ton message ; une erreur non bloquante affiche une notice « hook error ». Pour les détails d'exécution, lance Claude Code avec claude --debug : la doc précise que ce mode n'écrit pas dans le terminal mais dans un fichier journal, ~/.claude/debug/<id-de-session>.txt. Tu peux aussi utiliser /debug en cours de session pour activer le journal et connaître son chemin.
Sur Windows
Si un message parle de Git Bash introuvable (« Git Bash wasn't found »), Claude Code n'a pas trouvé Git Bash pour exécuter ta commande, et la doc précise que le hook en échec a alors bloqué l'outil. Elle consacre une section à ce cas : consulte-la pour la solution adaptée. Deux pistes simples : installer Git pour Windows, ou ajouter "shell": "powershell" au hook pour qu'il s'exécute dans PowerShell. Un script Node lancé avec node chemin/script.mjs, comme dans cette formation, évite aussi les commandes propres à bash.
Attention, dans un hook PowerShell, n'écris pas $CLAUDE_PROJECT_DIR tout seul : PowerShell le lit comme une variable locale vide. La doc demande $env:CLAUDE_PROJECT_DIR ou ${CLAUDE_PROJECT_DIR}, dans des guillemets doubles. Exemple tiré de la doc :
{
"type": "command",
"shell": "powershell",
"command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}
Le prompt de diagnostic
Mon hook ne se déclenche pas. Lis .claude/settings.json et ~/.claude/settings.json.
Vérifie : JSON valide, nom exact de l'événement, matcher (casse comprise),
présence d'un champ if, chemin du script. Liste ce qui cloche, propose
une correction, mais ne modifie rien sans mon accord.
Si ça coince
/hooksaffiche le hook mais rien ne se passe. Teste la commande seule (leçon 4.4), puis regarde Ctrl+O.- « command not found ». Utilise un chemin absolu ou
$CLAUDE_PROJECT_DIR. --debugn'affiche rien. C'est normal : ouvre le fichier journal dans~/.claude/debug/.- Message sur Git Bash. Installe Git pour Windows ou passe le hook en
"shell": "powershell".
À retenir
- Ordre de diagnostic : chargé ? dossier de confiance ? bon moment ? commande seule ? que dit Ctrl+O ?
/hooksconsulte, le fichier de réglages modifie.claude --debugécrit dans~/.claude/debug/, pas dans le terminal.- Sous Windows : Git Bash ou
"shell": "powershell"avec$env:CLAUDE_PROJECT_DIR.