Personnalisation pour les utilisateurs avancés de Claude Code : comment configurer les hooks

Les flux de travail fluides dans Claude Code finissent par accumuler des points de friction au fil du temps. Chaque fois que Claude écrit un fichier, Prettier doit être exécuté manuellement. Chaque fois qu'il exécute npm test, la même requête d'autorisation apparaît. Chaque session commence par coller le même contexte de projet standard dans le premier message.

La bonne nouvelle ? Les hooks éliminent ces points de friction. Ce sont des déclencheurs configurables qui s’activent avant ou après certaines actions et permettent d’intégrer directement des logiques personnalisées, des scripts et des commandes au fonctionnement de Claude.

Cet article traite de la configuration avancée pour les développeurs déjà familiarisés avec les bases de Claude Code. À la fin de cet article, vous comprendrez les huit types de hooks, quand les utiliser, comment les configurer et comment les déboguer en cas de problème.

Regardons cela de plus près. 

Qu'est-ce qu'un hook ?

Un hook est une commande shell personnalisée que vous créez pour s'exécuter automatiquement lorsqu'un événement ciblé se produit dans votre session de Claude Code, par exemple lorsque Claude est sur le point d'écrire un fichier ou lorsque vous soumettez une requête. Vous pouvez définir des hooks pour une multitude d'activités : intercepter des actions avant leur exécution, intégrer le contexte d'un agent, automatiser les approbations ou bloquer les opérations avant qu'elles ne se produisent.

Les hooks sont configurés dans vos fichiers de paramètres à l'aide d'une structure JSON avec des noms d'événements, des correspondances (pour filtrer les outils qui déclenchent le hook) et les commandes à exécuter. Ils s'exécutent dans votre environnement local avec vos droits d'utilisateur, reçoivent des informations sur l'événement déclencheur via stdin et renvoient leur réponse via les codes de sortie et stdout. Vous pouvez ainsi contrôler précisément le comportement de Claude Code sans modifier l'outil lui-même.

Pourquoi utiliser des hooks dans Claude Code ?

Les hooks résolvent trois catégories de problèmes.

Premièrement, ils éliminent les étapes manuelles répétitives. Au lieu d'exécuter votre formateur après chaque modification de fichier, un hook PostToolUse s'en charge automatiquement. Au lieu d'approuver npm test pour la centième fois, un hook PermissionRequest l'approuve automatiquement.

Deuxièmement, les hooks appliquent automatiquement les règles spécifiques aux projets. Vous pouvez bloquer les commandes dangereuses avant leur exécution, valider les chemins d’accès aux fichiers avant les écritures ou vous assurer que les conventions de nommage sont respectées. Ces garde-fous s'exécutent à chaque fois, pas seulement lorsque vous pensez à vérifier.

Troisièmement, les hooks intègrent un contexte dynamique sans intervention manuelle. Un hook SessionStart peut alimenter Claude avec votre état du service git actuel et votre liste TODO. Un hook UserPromptSubmit peut ajouter vos priorités de sprint à chaque requête. Claude reste informé sans que vous ayez à vous répéter.

Types de hooks Claude Code et quand les utiliser

Claude Code fournit huit événements hook qui couvrent l'ensemble du cycle de vie d'une session, du démarrage à l'achèvement en passant par l'exécution des outils. Chacun se déclenche à un moment spécifique, ce qui vous permet de contrôler précisément l'exécution de votre automatisation. Le choix du bon hook dépend de ce que vous souhaitez accomplir.

Les hooks en un coup d'œil

PreToolUse

C'est le hook le plus couramment utilisé ; il se déclenche après que Claude a choisi un outil à utiliser, mais avant que celui-ci ne soit effectivement exécuté. Votre script peut inspecter l'action planifiée et l'approuver, la bloquer, demander la confirmation de l'utilisateur ou modifier les paramètres, en utilisant un filtre pour déterminer quels outils déclenchent ce hook.

Cet exemple de hook PreToolUse évalue les écritures de fichiers avant leur exécution. Claude examine l'action planifiée selon des critères spécifiés et peut approuver, bloquer ou signaler les préoccupations en fonction de la logique de requête.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-file-path.sh"
          }
        ]
      }
    ]
  }
}

Quand utiliser PreToolUse :

• Bloquer les commandes Bash dangereuses comme rm -rf ou force pushes
• Approuver automatiquement les opérations sûres et répétitives pour réduire la fatigue liée aux requêtes
• Valider les chemins d'accès aux fichiers avant les écritures pour éviter les écrasements accidentels
• Modifier les entrées d'outils pour intégrer des valeurs par défaut spécifiques au projet

PermissionRequest

Ce hook se déclenche lorsque Claude affichera normalement une boîte de dialogue d'autorisation. Ce hook intervient juste avant l'affichage d'une requête de confirmation, laissant votre script décider s'il faut autoriser, refuser ou quand même demander à l'utilisateur.

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash(npm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-test-command.sh"
          }
        ]
      }
    ]
  }
}

Cet exemple approuve automatiquement toute commande Bash commençant par npm test. Le modèle de correspondance peut inclure des arguments pour un contrôle plus précis.

Quand utiliser PermissionRequest :

• Approuver automatiquement les commandes de test que vous exécutez des dizaines de fois par session
• Bloquer l'accès en écriture aux fichiers de configuration de production
• Autoriser les opérations de lecture sur des répertoires spécifiques sans invites
• Refuser toute commande qui correspond à un motif dangereux

PostToolUse

Se déclenche immédiatement après qu'un outil s'est exécuté avec succès. Votre script reçoit des informations sur ce qui s'est passé, y compris les résultats des outils, à l'aide de correspondances pour filtrer les outils qui le déclenchent.

Cet exemple de PostToolUse exécute Prettier sur n'importe quel fichier que Claude écrit ou modifie. La syntaxe pipe dans la correspondance signifie qu'elle se déclenche pour les outils Write et Edit.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Quand utiliser PostToolUse :

• Exécuter Prettier, Black ou gofmt après chaque écriture de fichier pour appliquer la mise en forme
• Enregistrement de toutes les modifications de fichiers dans une piste d'audit
• Déclencher des linters et afficher des avertissements après les modifications de code
• Envoi de notifications lorsque certaines opérations sont terminées

PreCompact

Se déclenche avant que Claude ne compacte le contexte de la conversation pour libérer de l'espace. La compaction résume les parties plus anciennes de la conversation, ce qui entraîne la perte de certains détails. Ce hook vous permet de préserver les informations avant que cela n'arrive.

Cet exemple de PreCompact sauvegarde la transcription avant le compactage automatique. La correspondance peut être « automatique » ou « manuelle » pour que vous puissiez faire la distinction entre le compactage automatique et les événements de compactage déclenchés par l'utilisateur.

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/backup-transcript.sh"
          }
        ]
      }
    ]
  }
}

Quand utiliser PreCompact :

• Sauvegarde de la transcription complète dans un fichier avant la synthèse
• Extraire et enregistrer des décisions importantes ou des extraits de code
• Enregistrer les étapes de session pour un examen ultérieur

SessionStart

Se déclenche lorsque Claude Code démarre une nouvelle session ou reprend une session existante. Tout ce que votre script produit est ajouté au contexte de la conversation ; Claude commence donc avec ces informations déjà chargées.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git status --short && echo '---' && cat TODO.md"
          }
        ]
      }
    ]
  }
}

Chaque session commence avec Claude connaissant votre statut git actuel et votre liste TODO. Stdout devient automatiquement le contexte.

Quand utiliser SessionStart :

• Transmettre à Claude votre branche Git actuelle et vos commits récents
• Charger le contenu de votre liste TODO ou de votre backlog de sprint
• Intégrer les détails de configuration spécifiques à l'environnement

Stop

Se déclenche lorsque Claude a fini de répondre et attend normalement votre prochaine entrée. Votre script peut inspecter ce que Claude a produit et décider si la tâche est vraiment terminée.

Le script peut renvoyer JSON avec "continue": true pour que Claude continue à travailler, ce qui est utile pour les flux de travail en plusieurs étapes :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review whether the task is complete. If all requirements are met, respond with 'complete'. If work remains, respond with 'continue' and specify what still needs to be done."
          }
        ]
      }
    ]
  }
}

Quand utiliser Stop :

• Forcer Claude à continuer jusqu'à ce que tous les éléments d'une liste de contrôle soient terminés
• Vérifier que les tests réussissent avant de considérer une tâche comme terminée
• Déclencher la génération d'un résumé à la fin d'une session
• Vérifier que le code généré se compile avant de s'arrêter

SubagentStop

Ce hook se déclenche chaque fois qu'un sous-agent créé à l'aide de l'outil Tâche termine son action. Fonctionne de la même manière que Stop, mais se déclenche spécifiquement lorsqu'un sous-agent termine son action (plutôt que l'agent principal). La configuration de SubagentStop reflète la structure du hook Stop :

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate the subagent's output. Verify the task was completed correctly and the results meet quality standards. If the output is satisfactory, respond with 'accept'. If issues exist, respond with 'reject' and explain what needs to be fixed."
          }
        ]
      }
          ]
  }
}

Quand utiliser SubagentStop :

• Vérifie que les résultats du sous-agent répondent aux critères de qualité
• Déclencher les actions de suivi en fonction des résultats de sous-agents
• Enregistrer l'activité des sous-agents pour le débogage ou l'audit

UserPromptSubmit

Se déclenche lorsque vous soumettez une requête, avant que Claude ne la traite. Tout ce que votre script sort via stdout est ajouté au contexte de Claude avec votre requête, ce qui rend UserPromptSubmit utile pour intégrer dynamiquement des informations que Claude devrait considérer.

Dans cet exemple, chaque fois que vous soumettez une requête, Claude reçoit le contenu de votre fichier de contexte sprint. Cela permet de tenir Claude informé des priorités actuelles, sans que vous ayez à les répéter.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ./current-sprint-context.md"
          }
        ]
      }
    ]
  }
}

Quand utiliser UserPromptSubmit :

• Intégrer le contexte actuel du sprint ou les priorités du projet dans chaque requête
• Vérifier les requêtes avant qu'elles n'atteignent Claude
• Bloquer certains types de requêtes en fonction du contenu
• Ajouter un contexte dynamique, comme des journaux d'erreurs récents ou des résultats de tests

Configuration et emplacements des fichiers

Les hooks se trouvent dans les fichiers de paramètres JSON à trois niveaux. Les hooks au niveau du projet sont stockés dans .claude/settings.json dans votre dépôt, ce qui les rend partageables avec votre équipe. Les hooks au niveau de l'utilisateur sont placés dans ~/.claude/settings.json et s'appliquent à tous vos projets. Les hooks de projet local sont placés dans .claude/settings.local.json pour une configuration personnelle que vous ne souhaitez pas enregistrer.

Les paramètres au niveau du projet ont préséance sur les paramètres au niveau de l'utilisateur. Des paramètres de stratégie gérés par l'entreprise sont également disponibles pour le contrôle organisationnel. Pour des détails complets, consultez les informations sur les paramètres de Claude Code.

Conseil de pro : c’est dans ce même fichier que vous pouvez définir des autorisations précises pour les actions de Claude, au niveau du projet, de l’utilisateur ou de l’environnement local. Par exemple, vous pouvez explicitement autoriser Claude à lire tous les fichiers d'un répertoire pour ne pas avoir à l'approuver à chaque fois, ou bloquer toute modification de fichiers sensibles.

Syntaxe de correspondance

Les correspondances vous permettent de filtrer les outils qui peuvent déclencher votre hook. Elles s'appliquent uniquement aux hooks PreToolUse, PostToolUse et PermissionRequest.

La simple correspondance de chaînes fonctionne exactement comme prévu : « Write » correspond uniquement à l'outil Write.

Par exemple :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

La syntaxe pipe vous permet de faire correspondre plusieurs outils : « Write|Edit » se déclenche pour l'un ou l'autre, tandis que les caractères génériques correspondent à tout : « * » ou une chaîne vide correspond à tous les outils.

Remarque : les correspondances étant sensibles à la casse, « bash » ne sera pas mis en correspondance avec l'outil Bash.

Pour un contrôle plus précis, des modèles d'arguments tels que « Bash(npm test*) » peuvent correspondre aux arguments de commande spécifiques. Les modèles d'outils MCP suivent le format « mcp__memory__.* » pour les outils Model Context Protocol.

Entrée, sortie et réponses structurées

Ce que reçoivent les hooks

Tous les hooks reçoivent un JSON via stdin contenant des informations de session et des données spécifiques à un événement. Les champs courants sont : session_id, transcript_path, cwd, permission_mode et hook_event_name.

En outre, les hooks liés aux outils reçoivent également tool_name et tool_input. Ces données permettent à vos scripts de prendre des décisions éclairées sur la manière de répondre.

Réponse des hooks

Les codes de sortie déterminent le résultat de base. Le code de sortie 0 est synonyme de succès, et stdout est traité pour JSON ou ajouté au contexte. Le code de sortie 2 indique une erreur de blocage : stderr devient le message d'erreur et l'action est empêchée.

Les autres codes de sortie indiquent des erreurs non bloquantes, stderr s'affichant en mode détaillé.

Au-delà des codes de sortie, les hooks peuvent renvoyer un JSON structuré pour plus de contrôle. Les champs incluent : decision (approve, block, allow ou deny), reason (explication présentée à Claude), continue (pour les hooks Stop pour forcer la poursuite) et updatedInput (pour modifier les paramètres de l'outil avant l'exécution).

Environnement et exécution

Les hooks ont accès aux variables d'environnement, notamment : CLAUDE_PROJECT_DIR pour le chemin racine du projet, CLAUDE_CODE_REMOTE, qui est true pour les environnements Web, et CLAUDE_ENV_FILE pour les hooks SessionStart pour conserver les variables. Les variables d'environnement standard de votre shell sont également accessibles.

À noter également : les hooks ont un délai d'expiration par défaut de 60 secondes, configurable par hook. Lorsque plusieurs hooks correspondent à un événement, ils s'exécutent en parallèle. Les commandes identiques sont automatiquement dédupliquées.

Considérations relative à la sécurité

Les hooks exécutent des commandes shell arbitraires avec vos autorisations d'utilisateur. Claude Code inclut une mesure de sécurité : les modifications directes des fichiers de configuration des hooks nécessitent un examen dans le menu /hooks avant de prendre effet. Cela empêche un code malveillant d'ajouter discrètement des hooks à votre configuration.

Toutefois, si vous configurez et approuvez des hooks, ils s'exécuteront à vos niveaux d'autorisation.

Conseil de pro : avant d'exécuter des commandes dans un environnement, tenez compte des risques. Si vous allez exécuter des commandes avec des hooks, adoptez des bonnes pratiques telles que : vérifier et assainir les entrées de stdin, mettre entre guillemets les variables shell pour prévenir les ajouts, utiliser des chemins absolus pour les scripts et éviter de traiter des fichiers sensibles comme .env ou les informations d'identification.

Débogage et tests

Claude Code enregistre tout dans les fichiers de transcription, ce qui fournit une visibilité sur les appels d'outils et les réponses sans aucune configuration. Chaque hook reçoit un champ transcript_path pointant vers un fichier JSONL contenant l'historique complet de la session. Vous pouvez utiliser un hook SessionStart pour consigner l'emplacement de chaque transcription :

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"Session: \" + .transcript_path' >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

Ensuite, suivez cette transcription pour voir Claude travailler en temps réel : tail -f /path/to/transcript.jsonl | jq .

Débogage spécifique à un hook

Pour le débogage spécifique à un hook, ajoutez l'enregistrement à vos scripts de hook. Les fichiers de transcription indiqueront ce qu'a fait Claude, mais pas pourquoi votre hook a décidé d'approuver ou de bloquer quelque chose.

Avec un peu d'effort supplémentaire, vous pouvez ajouter un petit script Bash qui encapsulera vos outils et enregistrera les informations supplémentaires. Par exemple, log-wrapper.sh :

#!/bin/bash
LOG=~/.claude/hooks.log
INPUT=$(cat)

TOOL=$(echo "$INPUT" |
 jq -r '.tool_name // "n/a"')
EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "n/a"')

echo "=== $(date) | $EVENT | $TOOL ===" >> "$LOG"

echo "$INPUT" | "$1"
CODE=$?

echo "Exit: $CODE" >> "$LOG"
exit $CODE

Ce petit script d'encapsulation stocke stdin dans une variable, enregistre l'horodatage et le nom de l'outil, puis transmet l'entrée à votre outil réel.

Une fois que vous avez écrit log-wrapper.sh, vous pouvez le préfixer à l'appel d'outil dans le hook :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "log-wrapper.sh your-tool-command.py"
          }
        ]
      }
    ]
  }
}

Conseil de pro : pour plus de conseils de débogage, consultez la documentation sur le débogage de Claude Code.

Créer vos propres hooks

Commencez par un simple hook qui résout un point de friction réel dans votre flux de travail. Le hook de mise en forme PostToolUse est un bon premier choix, car les retours sont immédiats et visibles. Une fois que cela fonctionne, développez en fonction de ce que vous apprenez.

Pour obtenir une documentation de référence complète, notamment tous les champs disponibles et les modèles avancés, consultez la documentation officielle sur les hooks.

Les hooks vous permettent de façonner Claude Code pour qu'il corresponde à votre flux de travail plutôt que d'adapter votre flux de travail à l'outil. Investir dans la configuration des hooks, c'est rentable à chaque session.

Commencez à utiliser des hooks pour personnaliser vos flux de travail Claude Code dès aujourd'hui.