Guide

Comment utiliser les hooks dans Claude Code

Vous voulez qu'une action ait lieu à chaque fois, comme formater un fichier après une modification de Claude ou recevoir une alerte quand Claude vous attend, sans espérer qu'il s'en souvienne. C'est exactement le rôle des hooks. Ce guide explique ce qu'ils sont, vous accompagne dans un premier hook et montre où les placer.

Mis à jour le 30 octobre 2026

Réponse rapide : un hook est une commande shell que Claude Code exécute automatiquement à un moment précis, par exemple avant le lancement d'un outil, après la modification d'un fichier ou quand Claude a besoin de votre intervention. Vous ajoutez les hooks sous une clé hooks dans un fichier de paramètres comme ~/.claude/settings.json (tous les projets) ou .claude/settings.json (un projet), puis tapez /hooks pour vérifier que Claude Code les voit.

Les noms d'événements, emplacements de fichiers et comportements ci-dessous proviennent de la documentation Claude Code d'Anthropic en octobre 2026. Claude Code évolue souvent : lancez claude update s'il manque quelque chose.

Ce que sont les hooks et pourquoi ils sont utiles

Les instructions d'un prompt ou d'un fichier CLAUDE.md sont des suggestions : Claude les suit généralement, mais c'est lui qui décide. Un hook, c'est différent. Claude Code lui-même exécute votre commande chaque fois que l'événement se produit : l'action est donc déterministe. Usages typiques tirés du guide d'Anthropic :

Notifications quand Claude attend une permission ou votre réponse.
Formatage automatique de chaque fichier après que Claude l'a modifié ou écrit.
Blocage des modifications de fichiers sensibles comme .env ou de tout ce qui se trouve dans .git/.
Ajout de contexte, par exemple pour rappeler à Claude les conventions du projet après la compaction de la conversation.

Parmi les événements les plus utilisés : SessionStart (une session démarre ou reprend), UserPromptSubmit (vous envoyez un prompt), PreToolUse (avant un appel d'outil, qu'il peut bloquer), PostToolUse (après un appel d'outil réussi), Notification, Stop (Claude a fini de répondre), PreCompact et SessionEnd. La liste complète de la référence des hooks est bien plus longue.

Configurer votre premier hook : une notification de bureau

Cet exemple, adapté de la démonstration d'Anthropic, vous alerte sur macOS chaque fois que Claude Code a besoin de votre attention.

Ouvrez ~/.claude/settings.json dans un éditeur de texte. Créez le fichier s'il n'existe pas.
Ajoutez un objet hooks avec une entrée Notification. Elle contient une liste de groupes de matchers ; chacun a un matcher (laissez une chaîne vide pour qu'il se déclenche à chaque notification) et une liste hooks avec un élément "type": "command".
Définissez la commande sur osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. Sous Linux, l'exemple d'Anthropic utilise plutôt notify-send. Pensez à échapper les guillemets doubles intérieurs en JSON.
Si le fichier a déjà une clé hooks, ajoutez Notification à côté des événements existants au lieu de remplacer tout l'objet.
Dans Claude Code, tapez /hooks. Le navigateur de hooks doit afficher votre nouveau hook sous Notification. Appuyez sur Échap pour revenir.
Demandez à Claude quelque chose qui nécessite une permission et passez à une autre fenêtre. Une notification doit apparaître.

Pour ne réagir qu'à certaines notifications, définissez le matcher sur un type comme permission_prompt (une demande de permission attend depuis environ six secondes) ou idle_prompt (Claude a terminé et vous n'avez rien tapé depuis environ une minute).

Un deuxième exemple : formater les fichiers après modification

Pour un hook de projet, placez la configuration dans .claude/settings.json à la racine du projet. Utilisez l'événement PostToolUse avec le matcher Edit|Write, pour qu'il ne s'exécute qu'après les outils de modification de fichiers. La commande d'exemple d'Anthropic lit le chemin modifié dans le JSON que Claude Code transmet sur l'entrée standard et le passe à Prettier : jq -r '.tool_input.file_path' | xargs npx prettier --write. Il faut que jq soit installé. Un hook réussi n'affiche rien dans la conversation ; vous verrez simplement le fichier reformaté.

Où configurer les hooks

Emplacement	S'applique à	Partagé ?
`~/.claude/settings.json`	Tous vos projets	Non, uniquement votre machine
`.claude/settings.json`	Un projet	Oui, peut être committé
`.claude/settings.local.json`	Un projet	Non, tenu hors de git
Paramètres de politique gérés	Toute l'organisation	Définis par les administrateurs
Le `hooks/hooks.json` d'un plugin	Tant que le plugin est activé	Fourni avec le plugin
Frontmatter d'un skill	Le reste de la session après l'appel du skill	Dans le fichier du skill
Frontmatter d'un subagent	Pendant l'exécution de ce subagent	Dans le fichier du subagent

Pour désactiver les hooks, définissez "disableAllHooks": true dans un fichier de paramètres. Les hooks des paramètres gérés continuent de s'exécuter, sauf si ce réglage y est aussi défini.

Comment un hook répond

Quand un événement se produit, Claude Code envoie ses détails en JSON sur l'entrée standard de votre commande. Votre commande répond par son code de sortie :

Code 0 : on continue. Pour certains événements, comme SessionStart, le texte simple écrit sur la sortie standard est ajouté au contexte de Claude.
Code 2 : bloquer l'action, si l'événement le permet. Écrivez la raison sur la sortie d'erreur ; pour PreToolUse, Claude la reçoit et peut changer d'approche.
Autres codes : généralement traités comme une erreur non bloquante ; l'action se poursuit et la transcription affiche une erreur de hook.

Pour un contrôle plus fin, terminez avec le code 0 et affichez plutôt un objet JSON. Choisissez une seule approche par hook.

Bon à savoir

Les hooks de commande ne peuvent pas lancer de commandes slash ni appeler des outils eux-mêmes.
Le délai par défaut des hooks de commande est de 10 minutes, plus court pour quelques événements ; définissez timeout (en secondes) par hook pour le modifier.
PostToolUse ne peut rien annuler, car l'outil s'est déjà exécuté. Utilisez PreToolUse pour empêcher une action.
Stop se déclenche chaque fois que Claude termine une réponse, pas seulement quand une tâche est finie.

Si cela ne fonctionne pas

Le hook ne se déclenche jamais : lancez /hooks et vérifiez qu'il apparaît sous le bon événement. Les matchers sont sensibles à la casse et doivent correspondre exactement au nom de l'outil, par exemple Edit et non edit.
« /hooks » n'affiche rien : vérifiez que le JSON est valide (ni virgules finales ni commentaires) et qu'il se trouve dans le bon fichier. Les modifications sont normalement prises en compte automatiquement ; sinon, redémarrez la session.
« hook error » dans la transcription : testez le script en lui envoyant un JSON d'exemple par un pipe et vérifiez echo $?. Utilisez des chemins absolus ou $CLAUDE_PROJECT_DIR pour les scripts, installez jq s'il manque et rendez les scripts exécutables avec chmod +x.
Aucune notification macOS : lancez une fois la commande osascript dans Terminal, puis activez Allow Notifications (Autoriser les notifications) pour Script Editor (Éditeur de script) dans System Settings > Notifications (Réglages Système > Notifications).

Suivez ce que chaque session laisse en suspens

Le plugin Workbranch pour Claude Code utilise un récapitulatif au démarrage de session : dans un dossier lié à un projet Workbranch, il affiche ce qui reste ouvert quand une session commence, et dire « save this to Workbranch » classe les tâches, décisions et questions ouvertes de la session dans ce projet. Voir Workbranch pour Claude. Vous débutez avec Claude Code ? Commencez par bien démarrer avec Claude Code.

Sources

Use Claude Code with your Pro or Max plan (centre d'aide Claude, consulté le 30 octobre 2026)
Automate actions with hooks (documentation Claude Code, consultée le 30 octobre 2026)

Questions fréquentes

Claude peut-il écrire un hook pour moi ?

Oui. Le guide d'Anthropic indique que vous pouvez décrire le hook voulu dans le prompt de Claude Code et demander à Claude de l'ajouter à vos paramètres. Vérifiez ensuite le résultat avec /hooks.

Un hook peut-il arrêter Claude même en mode bypass ?

Un hook PreToolUse qui renvoie une décision deny bloque l'outil dans tous les modes de permission, y compris bypassPermissions. C'est ce qui rend les hooks utiles pour des règles qu'on ne peut pas contourner en changeant de mode.

Existe-t-il des hooks qui utilisent un modèle plutôt qu'un script ?

Oui. En plus des commandes shell, un hook peut être une requête HTTP, un appel d'outil MCP, un prompt unique évalué par un modèle Claude, ou un hook agent expérimental avec accès aux outils.