Claude Code Hooks : Qu'est-ce que c'est et comment l'utiliser

Pour les Vibe Coders, des outils comme Claude Code d'Anthropic transforment la manière dont les développeurs écrivent, déboguent et gèrent leurs projets. Claude Code fonctionne comme un "outil de codage agentique" qui réside dans votre terminal, capable de comprendre l'intégralité de votre base de code, d'interagir avec votre système de fichiers, d'exécuter des commandes et même de naviguer sur le web pour la documentation. Il excelle dans des tâches telles que l'écriture de nouvelles fonctionnalités, la correction de bogues et le refactoring de code via des invites en langage naturel.

Cependant, une caractéristique essentielle des grands modèles linguistiques (LLM) est leur nature probabiliste. Bien que cela permette une résolution créative de problèmes, cela peut parfois entraîner une imprévisibilité. Vous pourriez vouloir que certaines actions – comme le linting d'un fichier après sa modification ou l'exécution de tests après l'écriture d'une nouvelle fonction – se produisent à chaque fois sans faute. Compter sur le LLM pour se souvenir de faire cela à chaque fois peut être incohérent.

C'est là que les Hooks de Claude Code entrent en jeu. Les Hooks sont une fonctionnalité puissante qui offre un contrôle déterministe et programmatique sur le comportement de Claude Code, garantissant que certaines actions se produisent toujours, plutôt que de dépendre du LLM pour choisir de les exécuter.

Cet article sert de guide complet pour comprendre, configurer et exploiter les Hooks de Claude Code afin de créer un flux de travail de développement entièrement automatisé et optimisé.

Que sont les Hooks de Claude Code ?

À la base, les Hooks de Claude Code sont des commandes shell définies par l'utilisateur qui s'exécutent automatiquement à des moments spécifiques du cycle de vie de Claude Code. Ils agissent comme des déclencheurs que vous pouvez configurer pour se lancer avant ou après certaines actions, vous permettant d'injecter votre propre logique personnalisée, vos scripts et vos commandes directement dans les opérations de Claude.

Les Hooks comblent le fossé entre l'assistance basée sur l'IA et l'automatisation basée sur des règles. Ils vous permettent d'appliquer des normes, d'automatiser les tâches répétitives et d'intégrer de manière transparente des outils externes dans votre flux de travail avec une fiabilité totale.

Il existe quatre événements clés du cycle de vie où un hook peut être déclenché :

1. PreToolUse : S'exécute avant que Claude n'utilise un outil spécifique (par exemple, avant d'écrire dans un fichier).
2. PostToolUse : S'exécute après qu'un outil a été utilisé avec succès (par exemple, après la modification d'un fichier).
3. Notification : S'exécute chaque fois que Claude envoie une notification (par exemple, lorsqu'il a besoin d'une entrée utilisateur ou qu'il a terminé une tâche longue).
4. Stop : S'exécute lorsque Claude a terminé de générer sa réponse et s'arrête.

En ciblant ces événements, vous pouvez créer des automatisations puissantes qui reflètent les meilleures pratiques du développement logiciel moderne, telles que les vérifications d'intégration continue (CI), mais à la vitesse du développement local.

L'anatomie des Hooks de Claude Code : une plongée approfondie dans la configuration

Pour utiliser les hooks, vous devez les définir dans le fichier de paramètres de Claude Code. Cela se fait en ajoutant une table [[hooks]] à votre fichier settings.toml, qui se trouve dans le répertoire .claude/ de votre projet. Chaque configuration de hook comporte quelques composants clés.

# Exemple de Hook dans .claude/settings.toml

[[hooks]]
# L'événement qui déclenche le hook.
event = "PostToolUse" 

# (Optionnel) Conditions pour l'exécution du hook.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# La commande shell à exécuter.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optionnel) Indique si la commande doit s'exécuter en arrière-plan.
run_in_background = false 

Décomposons chaque partie en détail.

Le champ event dans les Hooks de Claude Code (Obligatoire)

Cette chaîne spécifie lequel des quatre événements du cycle de vie déclenchera le hook.

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

Le hooks.matcher dans les Hooks de Claude Code (Optionnel)

Le matcher est ce qui vous permet de définir précisément quand un hook doit s'exécuter. Si vous omettez le matcher, le hook s'exécutera pour chaque instance de l'event spécifié. Par exemple, un hook PostToolUse sans matcher se déclenchera après chaque appel d'outil.

Le matcher possède trois champs que vous pouvez utiliser pour filtrer les événements :

• tool_name : Une chaîne qui correspond au nom de l'outil utilisé. C'est parfait pour cibler des actions spécifiques comme edit_file, git_commit ou run_command.
• file_paths : Un tableau de chaînes contenant des motifs glob. Le hook ne s'exécutera que si les fichiers impliqués dans l'utilisation de l'outil correspondent à l'un de ces motifs. Par exemple, ["*.py"] cible tous les fichiers Python, tandis que ["src/components/**/*.jsx"] cible les fichiers JSX dans un répertoire spécifique.
• query : Une chaîne qui correspond à l'entrée donnée à un outil. C'est utile pour des déclencheurs plus spécifiques, comme l'exécution d'un hook uniquement lorsqu'un outil run_command est utilisé avec une commande qui inclut npm.

Le champ command pour les Hooks de Claude Code (Obligatoire)

C'est le cœur du hook – la commande shell qui sera exécutée lorsque les conditions de déclenchement sont remplies. Cette commande s'exécute avec les mêmes permissions que votre compte utilisateur, elle peut donc faire tout ce que vous pouvez faire dans votre terminal.

Pour rendre les commandes dynamiques, Claude Code fournit un ensemble de variables d'environnement qui sont remplies avec le contexte de l'événement qui a déclenché le hook.

Variables d'environnement disponibles :

• $CLAUDE_EVENT_TYPE : Le type d'événement (PreToolUse, PostToolUse, etc.).
• $CLAUDE_TOOL_NAME : Le nom de l'outil qui a été utilisé (par exemple, edit_file).
• $CLAUDE_TOOL_INPUT : Les paramètres d'entrée bruts passés à l'outil au format JSON.
• $CLAUDE_FILE_PATHS : Une liste de chemins de fichiers séparés par des espaces, pertinents pour l'appel de l'outil. C'est incroyablement utile pour passer des fichiers aux formateurs, linters ou exécuteurs de tests.
• $CLAUDE_NOTIFICATION : Le contenu du message de notification (uniquement pour l'événement Notification).
• $CLAUDE_TOOL_OUTPUT : La sortie de l'exécution de l'outil (uniquement pour l'événement PostToolUse).

Le paramètre run_in_background pour les Hooks de Claude Code (Optionnel)

C'est une valeur booléenne (true ou false). Si défini sur true, la commande du hook sera exécutée dans un processus séparé, et Claude n'attendra pas qu'elle se termine avant de continuer. C'est idéal pour les tâches de longue durée comme les suites de tests complètes ou les processus de construction que vous ne voulez pas bloquer les actions ultérieures de Claude. La valeur par défaut est false.

Cas d'utilisation pratiques et exemples pour les Hooks de Claude Code

La véritable puissance des hooks est révélée lorsque vous les appliquez à des flux de travail de développement réels. Voici quelques exemples pratiques pour vous aider à démarrer.

1. Linting et formatage automatiques avec les Hooks de Claude Code

Appliquez un style de code cohérent à l'ensemble de votre projet automatiquement. Ce hook exécute le linter ruff et le formateur black sur tout fichier Python que Claude modifie.

Fichier : .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Commande pour linter, corriger et formater les fichiers Python modifiés.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Exécution automatique des tests avec les Hooks de Claude Code

Une pratique essentielle du développement piloté par les tests (TDD) consiste à écrire des tests, puis à écrire du code pour les faire passer, en itérant jusqu'à ce que tout fonctionne. Vous pouvez automatiser l'étape "exécuter les tests" avec un hook. Cet exemple exécute pytest chaque fois qu'un fichier dans le répertoire src/ ou tests/ est modifié.

Fichier : .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Les tests peuvent être lents, exécutez-les en arrière-plan.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Commande pour exécuter la suite de tests.
command = "pytest"

3. Notifications de bureau personnalisées via les Hooks de Claude Code

Si vous demandez à Claude d'effectuer une tâche de longue durée, vous pourriez vous éloigner de votre ordinateur. Ce hook utilise un outil en ligne de commande comme ntfy (un simple service de notification pub-sub basé sur HTTP) pour envoyer une notification push à votre téléphone ou votre bureau lorsque Claude a besoin de votre attention.

Fichier : .claude/settings.toml

[[hooks]]
event = "Notification"

# Envoie le contenu de la notification à un sujet ntfy.sh public.
# Vous pouvez héberger le vôtre pour plus de confidentialité.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Vérifications de bon sens avant le commit avec les Hooks de Claude Code

Tout comme les hooks Git, vous pouvez utiliser les Hooks de Claude Code pour garantir la qualité avant qu'un commit ne soit effectué. Cet exemple exécute un script personnalisé pour vérifier les clés API ou effectuer d'autres étapes de validation juste avant que Claude ne soit autorisé à utiliser l'outil git_commit.

Fichier : .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Commande pour exécuter un script de vérification avant le commit.
# Le script doit se terminer avec un code non nul pour arrêter le commit.
command = "sh ./.claude/pre-commit-checks.sh"

Configuration et débogage de vos Hooks de Claude Code

Commencer avec les hooks est simple, mais la vérification et le débogage sont essentiels pour s'assurer qu'ils fonctionnent comme prévu.

1. Créez votre configuration : Assurez-vous d'avoir un fichier .claude/settings.toml dans le répertoire racine de votre projet. Ajoutez-y vos configurations [[hooks]].
2. Vérifiez la configuration : Après avoir enregistré votre fichier settings.toml, exécutez la commande /hooks dans l'interface du terminal de Claude Code. Cette commande spéciale affichera vos configurations de hook actuellement chargées, vous permettant de voir instantanément si Claude les a correctement analysées.
3. Vérifiez les erreurs :

• TOML invalide : Assurez-vous que votre fichier settings.toml a une syntaxe valide. Un crochet ou une citation mal placé peut empêcher son chargement.
• Problèmes de commande : Testez votre command directement dans votre shell pour vous assurer qu'elle fonctionne comme prévu. Vérifiez les fautes de frappe et assurez-vous que les exécutables nécessaires (black, pytest, ntfy, etc.) sont dans le PATH de votre système.
• Débogage des variables : Pour voir les valeurs que contiennent les variables d'environnement, utilisez echo pour les écrire dans un fichier journal. Par exemple : command = "echo 'Outil : $CLAUDE_TOOL_NAME, Fichiers : $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

Conclusion : La puissance des Hooks de Claude Code

Les Hooks de Claude Code élèvent l'outil d'un assistant de codage très performant à un partenaire de développement entièrement intégré et déterministe. En définissant des règles simples et puissantes, vous pouvez automatiser les parties banales mais critiques de votre flux de travail, vous libérant ainsi pour vous concentrer sur les aspects complexes et créatifs de l'ingénierie logicielle. Qu'il s'agisse d'appliquer la qualité du code, de simplifier votre boucle TDD ou d'intégrer des services tiers, les hooks fournissent le cadre robuste nécessaire pour adapter Claude Code à vos besoins exacts.

À mesure que vous vous familiariserez avec les capacités de Claude Code, commencez modestement avec un simple hook de formatage, puis explorez des automatisations plus complexes. Vous découvrirez rapidement que cette fonctionnalité est essentielle pour construire un environnement de développement assisté par l'IA prévisible, efficace et véritablement personnalisé.