Chapitre 3 · Chapitre 3 · Écrire sa première configuration
3.2 L'anatomie d'une configuration
Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.
Suivre gratuitementVoici la configuration de la vidéo, ligne par ligne. Elle se trouve dans .claude/settings.json, à la racine du projet.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/verifier.mjs\""
}
]
}
]
}
}
Niveau par niveau
"hooks": un seul objet qui contient tous tes hooks."PostToolUse": le nom de l'événement. C'est une liste, car tu peux avoir plusieurs groupes pour le même événement."matcher": le filtre du groupe.- Le second
"hooks": la liste des actions (les handlers) à lancer quand le filtre correspond. "type": "command"et"command": la commande à exécuter.
Les champs facultatifs d'un handler
"timeout": le délai maximal, en secondes. Par défaut, 10 minutes pour un hook command. Exemple :"timeout": 30."if": un filtre plus fin, vu en leçon 2.4."shell":"bash"ou"powershell", utile sous Windows (leçon 3.4).
$CLAUDE_PROJECT_DIR
Cette variable contient le chemin de la racine du projet, là où la session a démarré. La doc précise qu'elle reste fixe même quand Claude change de dossier. L'utiliser évite les erreurs « command not found » quand Claude travaille dans un sous-dossier. Mets-la entre guillemets si le chemin peut contenir des espaces : c'est pour ça qu'on écrit \"$CLAUDE_PROJECT_DIR/...\". Le \" est un guillemet échappé : dans une chaîne JSON, un guillemet doit être précédé d'une barre oblique inverse.
Ajouter un événement sans tout casser
Si ton fichier contient déjà des hooks, ajoute le nouvel événement à côté des autres, dans le même objet "hooks". Ne le remplace pas. La doc montre précisément cette erreur : chaque nom d'événement est une clé du même objet. Voici le bon résultat avec deux événements :
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/proteger.mjs\"" }]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/verifier.mjs\"" }]
}
]
}
}
Note la virgule après le crochet fermant de PreToolUse, et l'absence de virgule après celui de PostToolUse, le dernier.
Le prompt pour ajouter un hook proprement
Ajoute à .claude/settings.json un hook <événement> avec le matcher <matcher>
qui lance <commande>. Garde tous les hooks existants, ne remplace rien,
vérifie que le JSON final est valide et montre-moi le fichier complet
avant de l'enregistrer.
Les erreurs de syntaxe
Le JSON n'accepte ni commentaires ni virgule après le dernier élément d'une liste. Une seule virgule en trop, et aucun hook n'apparaît. Si tu as un doute, demande à Claude Code : « Vérifie que .claude/settings.json est un JSON valide ».
Si ça coince
- Aucun hook n'apparaît. Cherche une virgule finale ou un commentaire
//: le JSON les refuse. - Ton ancien hook a disparu. Tu as remplacé l'objet
"hooks"au lieu d'y ajouter une clé. Restaure-le à côté du nouveau. - Erreur sur les guillemets. Dans la chaîne
"command", chaque guillemet intérieur s'écrit\". - Ton
timeoutsemble ignoré. Il est en secondes :600veut dire dix minutes, pas 600 millisecondes.
À retenir
- Structure :
hooks→ événement → liste de groupes (matcher+hooks) → handlers (type,command). - Chaque événement est une clé du même objet
hooks: on ajoute, on ne remplace pas. $CLAUDE_PROJECT_DIRentre guillemets pour des chemins fiables.- Pas de commentaire, pas de virgule finale.