# Hooks dans Claude Code pour débutants : automatiser les actions répétitives > Guide pratique complet sur la configuration des Hooks dans Claude Code : linting automatique, formatage, vérifications de sécurité avant commit, notifications et automatisation Headless. ## 1. Qu'est-ce que les Hooks dans Claude Code et pourquoi sont-ils essentiels En travaillant avec un assistant IA dans le terminal, les développeurs sont souvent contraints de répéter les mêmes commandes routinières : *"lancez maintenant ESLint"*, *"formatez le code via Prettier"*, *"vérifiez les types avant le commit"*. Même si ces règles sont inscrites dans les instructions système `CLAUDE.md`, le modèle de langage peut parfois oublier de les appliquer ou les sauter pour économiser des tokens. Les **Hooks** dans Claude Code résolvent ce problème radicalement : il s'agit de déclencheurs déterministes qui exécutent automatiquement des commandes système ou des scripts à des moments précis du cycle de vie de l'assistant. La logique des hooks est simple : > **Si Claude a effectué l'événement X → le système d'exploitation garantit le lancement de l'action Y.** ```mermaid flowchart LR subgraph Текстова_інструкція["CLAUDE.md (Ймовірнісна)"] A["Промпт: 'Завжди запускай лінтер'"] --> B{"Модель пам'ятає?"} B -->|Іноді| C["Запуск перевірки"] B -->|Пропустила| D["Помилки накопичуються"] end subgraph Нативний_Hook["Hooks у settings.json (Детермінована)"] E["Подія: Редагування файлу"] --> F["Автоматичний тригер ОС"] F --> G["Гарантоване виконання npx eslint"] end ``` ### Comparaison des approches d'automatisation | Caractéristique | Prompts manuels | Instructions dans CLAUDE.md | Hooks natifs | | :--- | :--- | :--- | :--- | | **Fiabilité d'exécution** | Faible (dépend de la mémoire humaine) | Moyenne (comportement probabiliste du LLM) | 100% (interception déterministe des événements) | | **Consommation de tokens** | Élevée (les tokens de requête sont consommés à chaque fois) | Moyenne (la règle est chargée dans chaque contexte) | Nulle (exécution locale dans le shell) | | **Vitesse de réaction** | Lente (saisie manuelle des commandes) | Nécessite un tour de génération supplémentaire | Instantanée (appel natif du processus) | | **Possibilité de blocage** | Absente | Absente | Oui (un exit code non nul stoppe l'action) | > [!NOTE] > Les hooks Claude Code se configurent au format JSON dans le fichier `.claude/settings.json` au niveau d'un dépôt spécifique ou globalement dans `~/.claude/settings.json`. --- ## 2. Cycle de vie des événements : PreToolUse, PostToolUse, Notification, Stop Claude Code prévoit quatre points d'interception fondamentaux (événements) auxquels vous pouvez associer des commandes automatisées. ```mermaid sequenceDiagram autonumber actor Dev as Розробник participant Agent as Claude Code participant Hook as Система Hooks participant Tool as Інструмент (Bash/Edit/Write) Dev->>Agent: Запит на модифікацію коду Agent->>Hook: Спроба виклику інструмента Note over Hook: PreToolUse Hook Hook-->>Agent: Перевірка пройдена (Exit Code 0) Agent->>Tool: Виконання операції Tool-->>Agent: Результат успішний Agent->>Hook: Подія завершення операції Note over Hook: PostToolUse Hook Hook-->>Agent: Результат лінтингу / форматування Agent->>Hook: Завершення відповіді моделі Note over Hook: Stop Hook (Сповіщення) Agent-->>Dev: Фінальна відповідь ``` ### Points de déclenchement principaux 1. **`PreToolUse` (Avant l'utilisation de l'outil) :** se déclenche *avant* que l'agent n'exécute une action. Si la commande du hook retourne une erreur (exit code différent de 0), l'exécution de l'action est bloquée. C'est l'endroit idéal pour les vérifications de sécurité avant les commits ou les pushes. 2. **`PostToolUse` (Après l'utilisation de l'outil) :** se déclenche *immédiatement après* l'exécution réussie d'un outil. C'est le déclencheur le plus populaire pour le formatage automatique du code (Prettier) ou le linting du fichier modifié (ESLint). 3. **`Notification` (Notification) :** s'active lorsque l'assistant doit envoyer un message système important ou demander une autorisation supplémentaire. 4. **`Stop` (Fin de réponse) :** se déclenche au moment où Claude Code a complètement terminé la génération de la réponse et attend le prochain message utilisateur. Utilisé pour la lecture de signaux sonores et les notifications desktop. ![Points de déclenchement des Hooks dans le cycle de vie](/api/guides-media/automation/hooks-automation-guide-for-beginners/images/hooks-automation-guide-for-beginners-extra-02.webp) --- ## 3. Structure de configuration dans settings.json et syntaxe Matcher La configuration des hooks est stockée dans le fichier `.claude/settings.json`. Si ce fichier n'existe pas encore à la racine de votre projet, créez-le. ### Syntaxe de configuration de base ```json { "hooks": { "PreToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "echo 'Починається редагування файлу...'" } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash-команда завершена успішно'" } ] } ] } } ``` ### Fonctionnement du champ Matcher Le champ `matcher` détermine sur quel outil spécifique de l'agent le hook doit réagir : - `"Edit"` — intercepte la modification de fichiers existants. - `"Write"` — se déclenche lors de la création d'un nouveau fichier ou d'une réécriture complète. - `"Bash"` — réagit au lancement de n'importe quelle commande console. - `"Bash(git commit*)"` — modèle précis qui filtre les appels Bash commençant par la commande `git commit`. - `"*"` — sélecteur universel (wildcard), qui se déclenche sur n'importe quel outil de l'agent. > [!TIP] > Les modèles `matcher` sont sensibles à la casse. Utilisez les noms standard des outils Claude Code : `Edit`, `Write`, `Bash`, `Glob`, `Grep`. --- ## 4. Linting et formatage automatiques (ESLint + Prettier) Le scénario quotidien le plus pratique consiste à déléguer le formatage et la vérification initiale du style aux utilitaires `Prettier` et `ESLint`. Grâce à cela, le code est toujours sauvegardé dans le dépôt dans un état impeccable. ### Configuration PostToolUse pour ESLint et Prettier ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ] } } ``` ### Analyse des drapeaux de sécurité dans la commande - `"$CLAUDE_FILE_PATH"` — variable d'environnement dynamique dans laquelle Claude insère automatiquement le chemin complet vers le fichier dès qu'il est modifié par l'agent. - `2>/dev/null` — supprime les sorties d'erreur inutiles du flux stderr pour ne pas surcharger le terminal. - `|| true` — construction bash cruciale. Elle garantit que même si le linter trouve des erreurs irrécupérables et retourne le code `1`, le hook lui-même se terminera avec le code `0` et n'arrêtera pas le fonctionnement ultérieur de l'agent. ```mermaid flowchart TD A["Claude викликає Edit"] --> B["Файл збережено на диску"] B --> C["PostToolUse тригер"] C --> D["npx eslint --fix $CLAUDE_FILE_PATH"] D --> E{"Успішно або || true"} E --> F["Агент продовжує вирішувати задачу"] ``` --- ## 5. Barrières de sécurité avant git commit (TypeCheck + Tests) Si nous avons utilisé des hooks doux avec `|| true` pour le formatage, la fixation des modifications dans le système de contrôle de version nécessite un contrôle qualité strict (Quality Gate). À l'aide de `PreToolUse`, vous pouvez bloquer la création d'un commit si le projet contient des erreurs de compilation TypeScript ou si les tests unitaires échouent. ### Configuration d'un hook Pre-commit bloquant ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm run lint" } ] } ] } } ``` ### Ce qui se passe en cas de détection d'erreurs 1. Claude formule la commande `git commit -m "..."`. 2. Avant son exécution, le système active `PreToolUse`. 3. Les commandes de validation sont lancées : `npm run typecheck` et `npm run lint`. 4. **Si une erreur est détectée :** le processus retourne un code de sortie non nul (exit code 1). 5. Claude Code capture la sortie de l'erreur du compilateur directement dans son contexte. 6. Au lieu d'un commit cassé, l'assistant analyse le texte de l'erreur, corrige automatiquement les types dans le code et effectue une nouvelle tentative propre de commit. > [!IMPORTANT] > Notez bien : dans les vérifications bloquantes `PreToolUse`, **n'utilisez jamais** `|| true`, sinon la vérification sera toujours considérée comme réussie et la barrière de sécurité cessera de fonctionner. --- ## 6. Notifications audio et desktop à la fin des tâches (Stop Hook) Les refactoring complexes ou l'exécution de suites de tests complètes peuvent durer de 2 à 10 minutes. Plutôt que de fixer sans relâche le terminal, configurez des notifications via l'événement `Stop`. :::tabs @tab macOS ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff && osascript -e 'display notification \"Завдання виконано!\" with title \"Claude Code\"'" } ] } ] } } ``` @tab Linux (Ubuntu / Debian) ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || notify-send 'Claude Code' 'Завдання успішно виконано!'" } ] } ] } } ``` @tab Windows (WSL / PowerShell) ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "powershell.exe -c \"[System.Media.SystemSounds]::Asterisk.Play(); [System.Console]::Beep(800, 250)\"" } ] } ] } } ``` ::: > [!TIP] > La notification se déclenche uniquement lorsque l'agent termine complètement la génération de la réponse finale, et non entre les appels intermédiaires aux outils. --- ## 7. Transmission du contexte via les variables d'environnement Pour que les scripts d'automatisation soient flexibles et adaptatifs, Claude Code exporte automatiquement les métadonnées de l'opération courante dans les variables d'environnement système (Environment Variables). ![Variables d'environnement Claude Code pour les hooks](/api/guides-media/automation/hooks-automation-guide-for-beginners/images/hooks-automation-guide-for-beginners-extra-01.webp) ### Référentiel des variables système Claude Code | Variable d'environnement | Type de valeur | Description et exemple de contenu | | :--- | :--- | :--- | | **`$CLAUDE_FILE_PATH`** | Chemin absolu | Chemin vers le fichier spécifique actuellement créé ou édité (`/Users/dev/project/src/index.ts`) | | **`$CLAUDE_TOOL_NAME`** | Identifiant textuel | Nom de l'outil qui a initié l'événement (`Edit`, `Write`, `Bash`) | | **`$CLAUDE_PROJECT_DIR`** | Chemin absolu | Répertoire racine du projet où la session actuelle de Claude Code est lancée | ### Exemple de script Bash contextuel pour un hook Créons le script `.claude/hooks/smart-validator.sh` : ```bash #!/usr/bin/env bash set -e # Перевіряємо, чи існує файл і яке у нього розширення if [[ -f "$CLAUDE_FILE_PATH" ]]; then case "$CLAUDE_FILE_PATH" in *.ts|*.tsx) echo "⚡ Валідація TypeScript файлу: $CLAUDE_FILE_PATH" npx eslint --fix "$CLAUDE_FILE_PATH" || true ;; *.json) echo "🔍 Перевірка валідності JSON..." jq empty "$CLAUDE_FILE_PATH" 2>/dev/null || echo "Помилка формату JSON!" ;; *.md) echo "📝 Оновлено документацію: $(basename "$CLAUDE_FILE_PATH")" ;; esac fi ``` Désormais, dans `.claude/settings.json`, il suffit d'indiquer l'appel de ce script : ```json { "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash .claude/hooks/smart-validator.sh" } ] } ] } } ``` --- ## 8. Pattern « CI-in-a-Loop » : feedback continu Dans le développement traditionnel sans hooks, un pattern de rupture apparaît : l'agent apporte des modifications à une dizaine de fichiers, puis le build du projet se lance et génère une avalanche de 40 erreurs de types. Il est difficile pour l'agent de déterminer quelle modification précise a causé la panne. **CI-in-a-Loop (Court cycle de feedback)** inverse ce processus : ```mermaid flowchart TD A["Claude вносить правку в код"] --> B["Миттєвий запуск tsc"] B --> C{"Є помилка?"} C -->|Так| D["Claude бачить 1 точкову помилку"] D --> E["Миттєвий фікс за 5 секунд"] E --> B C -->|Ні| F["Перехід до наступного рядка/файлу"] ``` ### Configuration de l'audit cyclique TypeScript ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -n 20 || true" } ] } ] } } ``` ### Pourquoi utiliser impérativement `head -n 20` Si la sortie du compilateur retourne des centaines de lignes de logs, elles entrent dans le contexte du modèle et peuvent saturer la limite de tokens. La limitation via `head -n 20` affiche les premières erreurs les plus critiques, offrant au modèle un repère précis pour une correction immédiate sans surcharger la session. --- ## 9. Automatisation Headless : mode -p, Cron et Git Hooks Les hooks peuvent être combinés avec le mode autonome (headless) de Claude Code — le drapeau `-p` (print/prompt). Cela permet d'automatiser l'exécution des tâches entièrement sans intervention humaine. ```mermaid flowchart LR A["Розклад Cron (02:00)"] --> B["Скрипт nightly-audit.sh"] B --> C["claude -p 'Run test suite, fix bugs, commit'"] C --> D["Хуки PostToolUse контролюють код"] D --> E["Автоматичний Push результату"] ``` ### Script autonome d'audit nocturne (nightly-audit.sh) ```bash #!/usr/bin/env bash cd /var/www/my-project # Запуск Claude Code в автономному режимі з фіксованим завданням claude -p "Run full test suite. If any tests fail, inspect the stack trace and fix them. Ensure typecheck passes. Finally, commit all fixes with a conventional commit." >> /var/log/claude-audit.log 2>&1 ``` ### Configuration de l'horaire d'exécution via Cron Ouvrez le planificateur de tâches (`crontab -e`) et configurez l'exécution chaque nuit à 03:00 : ```text 0 3 * * * /usr/local/bin/nightly-audit.sh ``` ### Lancement de la vérification dans un Git Hook natif (.git/hooks/post-merge) Pour qu'une analyse de compatibilité se lance automatiquement après chaque récupération de mises à jour via `git pull` : ```bash #!/usr/bin/env bash # .git/hooks/post-merge echo "🚀 Запуск автоматичної перевірки залежностей через Claude..." claude -p "Check if package.json was updated. If so, run npm install, verify build, and report summary." ``` N'oubliez pas d'accorder les droits d'exécution au script : `chmod +x .git/hooks/post-merge`. --- ## 10. Meilleures pratiques d'ingénierie et règles de sécurité des Hooks Des hooks mal configurés peuvent boucler l'exécution ou bloquer le fonctionnement du terminal. Respectez quatre règles fondamentales d'hygiène d'ingénierie. ### Quatre règles de conception sécurisée des hooks 1. **Rapidité extrême :** Les hooks avec l'événement `PostToolUse` s'exécutent après chaque modification de fichier. Si un hook prend plus de 1-2 secondes, le travail interactif avec Claude deviendra lent et inconfortable. Lancez les tests E2E lourds uniquement dans `PreToolUse` avant le commit, mais pas après chaque `Edit`. 2. **Journalisation obligatoire de la sortie :** Redirigez toujours la sortie des scripts de diagnostic vers un fichier log temporaire : ```bash "command": "bash .claude/hooks/check.sh >> /tmp/claude-hooks.log 2>&1 || true" ``` Si un hook cesse de se déclencher, vous pourrez ouvrir immédiatement `/tmp/claude-hooks.log` et trouver la cause. 3. **Test isolé dans un terminal propre :** Avant d'ajouter une commande à `settings.json`, exécutez-la vous-même dans un shell standard. Si la commande produit une erreur dans la console, elle cassera garantitivement la session Claude Code. 4. **Prévention de la récursion infinie :** Ne configurez jamais une commande dans `PostToolUse` qui modifie elle-même les fichiers du projet sans drapeaux d'ignorance (par exemple, un script tiers qui appelle un `Edit` répétitif), sinon l'agent entrera dans une boucle d'appels éternelle. > [!WARNING] > Ne lancez pas via les hooks des commandes qui attendent une saisie interactive de l'utilisateur (par exemple, confirmation `read -p` ou `sudo` avec demande de mot de passe). Cela entraînera le gel du processus terminal. --- ## 11. Atelier pratique, mémo et checklist de synthèse Pour démarrer rapidement dans votre propre projet, utilisez un mémo synthétique prêt à l'emploi et une configuration production éprouvée. ![Mémo pour choisir le type de Hook pour l'automatisation](/api/guides-media/automation/hooks-automation-guide-for-beginners/images/hooks-automation-guide-for-beginners-extra-03.webp) ### Fichier de configuration prêt à l'emploi `.claude/settings.json` Copiez cette configuration étalon dans le dossier `.claude` de votre projet : ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm test" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Роботу завершено!\" with title \"Claude Code\"' 2>/dev/null || true" } ] } ] } } ``` ### Auto-vérification rapide > **1. En quoi `PreToolUse` diffère-t-il fondamentalement de `PostToolUse` ?** > > > [!TIP] > > **Réponse :** `PreToolUse` se lance *avant* l'exécution de l'action de l'outil et peut la bloquer en cas d'exit code non nul. `PostToolUse` se lance *après* la fin réussie de l'opération et est utilisé pour le formatage ou le linting. > **2. Pourquoi ajoute-t-on `|| true` dans les hooks de formatage ?** > > > [!TIP] > > **Réponse :** Pour éviter que les erreurs du linter ou du formateur ne retournent un statut critique et n'arrêtent le processus de génération de la réponse de l'agent. > **3. Quelle variable d'environnement contient le chemin vers le fichier venant d'être édité ?** > > > [!TIP] > > **Réponse :** La variable `$CLAUDE_FILE_PATH`. ### Checklist de synthèse pour l'implémentation des Hooks - [ ] Le répertoire `.claude/` et le fichier `settings.json` ont été créés à la racine du projet. - [ ] Le formatage automatique des fichiers modifiés est configuré via `PostToolUse` + `Prettier`. - [ ] Les barrières de sécurité avant commit (`PreToolUse`) sont en place avec TypeCheck et Tests. - [ ] Les notifications `Stop` sont configurées pour les longues sessions. - [ ] Les scripts utilisent correctement les variables d'environnement (`$CLAUDE_FILE_PATH`). - [ ] Les logs sont activés pour le débogage des hooks.