Les hooks Claude Code sont des déclencheurs déterministes qui exécutent vos commandes shell à des points spécifiques du cycle de vie de Claude Code. Utilisez-les pour auto-formater les fichiers après les modifications, appliquer des règles de projet, bloquer les opérations risquées, injecter du contexte au début de la session ou vous notifier lorsque des entrées sont nécessaires, sans compter sur le modèle pour "se souvenir".

Pourquoi les hooks sont importants

Les invites sont parfaites pour les suggestions; les hooks sont des garanties. Ils se déclenchent chaque fois que l'événement correspondant se produit (par exemple, avant l'exécution d'un outil, après une modification, lors du démarrage/fin d'une session). Cela signifie un formatage cohérent, l'application de politiques et des garde-fous pour votre équipe, sans nécessiter d'invite supplémentaire.

Ce que les hooks Claude Code peuvent faire

• Prévenir les actions risquées : Bloquez les écritures sur .env, la configuration de production, ou /.git (Utilisez PreToolUse avec un contrôle du code de sortie.)

• Appliquer automatiquement les normes : Exécutez prettier, gofmt ou votre linter après chaque édition/écriture (PostToolUse).

• Injecter automatiquement du contexte : Au démarrage de session, chargez les derniers tickets ou une liste de vérification de codage dans la conversation.

• Notifications sans clic : Notifications sur le bureau lorsque Claude nécessite une approbation (Notification).

• Contrôler les invites/outils : Approuvez, refusez ou demandez une confirmation via le contrôle de décision PreToolUse / PermissionRequest.

Les hooks sont configurés dans les paramètres utilisateur, projet, ou projet local, et peuvent également être appliqués via les paramètres de stratégie d'entreprise. Claude Code

Les événements de hooks que vous utiliserez réellement

• PreToolUse / PermissionRequest / PostToolUse — encadrer les appels d'outils (Bash, Edit, Write, Read, Grep, WebFetch, Task/subagents). Autoriser, refuser ou demander; modifier les entrées; ou donner un retour après.

• UserPromptSubmit — valider ou enrichir les invites avant que Claude ne les traite ; vous pouvez injecter du texte ou un contexte structuré.

• Démarrage de session / Fin de session — configurer l'environnement, charger le contexte, et nettoyer/loguer à la fin.

• Notification, Stop, SubagentStop, PreCompact — alertes, contrôle de fin de réponse, et hooks de compactage.

Une configuration rapide et sécurisée (5 étapes)

1. Ouvrir l'interface des Hooks : exécutez /hooks dans Claude Code. Choisissez un événement (par exemple, PreToolUse).

2. Ajoutez un matcher : par exemple, Edit|Write pour intercepter les modifications de fichier, ou Bash pour gérer les commandes shell. * correspond à tout.

3. Ajoutez le hook : choisissez type: "command" et entrez votre commande shell (elle reçoit du JSON sur stdin; utilisez jq/Python pour analyser).

4. Choisir le stockage :

   • ~/.claude/settings.json (utilisateur),

   • .claude/settings.json (projet, engagement dans le dépôt),

   • .claude/settings.local.json (local uniquement),

   • ou politique d'entreprise (appliquée de manière centralisée).

5. Vérifiez et testez : /hooks affiche votre configuration; exécutez une commande rapide et vérifiez votre journal/sortie.

Exemples prêts à copier

1) Journaliser chaque commande Bash (audit rapide)

Enregistrez sous PreToolUse avec le matcher Bash :

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

Cette opération s'exécute avant chaque appel d'outil Bash et ajoute une ligne à un fichier journal. Claude Code

2) Autoformater TypeScript après les modifications/écritures

PostToolUse avec le matcher Edit|Write :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Claude Code

3) Protéger les fichiers sensibles (bloquer avec le code de sortie 2)

PreToolUse avec le matcher Edit|Write :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; d=json.load(sys.stdin); p=d.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(x in p for x in ['.env','package-lock.json','.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

Le code de sortie 2 bloque l'action et présente votre stderr à Claude (et/ou à l'utilisateur) selon les règles de chaque événement. Claude Code

4) Recevoir des alertes sur votre bureau lorsque Claude a besoin de vous

Hook de Notification :

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Awaiting your input'" }
        ]
      }
    ]
  }
}

Claude Code

5) Précharger le contexte au démarrage de la session

Démarrage de session peut injecter des orientations supplémentaires ou une liste de vérification :

• Écrire du texte brut sur stdout (code de sortie 0) pour ajouter du contexte, ou

• Retourner du JSON avec hookSpecificOutput.additionalContext.

Contrôle avancé : codes de sortie & décisions JSON

• 0 : succès. stdout peut être analysé en tant que JSON pour un contrôle structuré (par exemple, "allow"|"deny"|"ask" sur PreToolUse; "block" sur PostToolUse/Stop; ajouter additionalContext).

• 2 : erreur bloquante. Ignore JSON; utilise stderr comme message et bloque selon les règles de chaque événement (par exemple, refuser un PreToolUse).

• Autre non-zéro : non-bloquant; affiche stderr en mode détaillé.

Utilisation CI et non interactive (bonus)

Combinez les hooks avec le mode sans tête pour exécuter Claude Code dans CI, des scripts de construction ou des travaux de style pré-commit : claude -p "<prompt>" --output-format stream-json. Le mode sans tête est par session, donc déclenchez-le à chaque exécution. Anthropic

Essentiels de la sécurité & gouvernance

• Les hooks s'exécutent automatiquement avec les informations d'identification de votre utilisateur ; révisez les scripts attentivement et suivez les Meilleures Pratiques de Sécurité (les variables de citation, valider les entrées, éviter les chemins sensibles, utiliser des chemins absolus).

• Les modifications de configuration ne s'appliquent pas à chaud : Claude crée un instantané des hooks au démarrage de la session et vous demande de revoir les modifications dans /hooks—une protection contre les modifications malveillantes.

• L'entreprise peut appliquer des hooks de politique à l'échelle de l'organisation pour garantir la cohérence.

FAQs

Qu'est-ce que les hooks Claude Code ?
Commandes shell définies par l'utilisateur qui s'exécutent à des événements spécifiques du cycle de vie dans Claude Code (par exemple, PreToolUse, PostToolUse, SessionStart) pour appliquer des règles, automatiser des tâches ou ajouter du contexte. Claude Code

Où les configurer ?
Dans ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, ou via les paramètres de politique d'entreprise ; /hooks offre un éditeur interactif. Claude Code

Comment bloquer les actions dangereuses ?
Retournez le code de sortie 2 depuis un hook PreToolUse/PermissionRequest pour refuser l'action et envoyer votre message d'erreur à Claude ; ou utilisez le contrôle de décision JSON pour "refuser/demander/accepter". Claude Code

Puis-je ajouter du contexte automatiquement ?
Oui—UserPromptSubmit et Démarrage de session peuvent injecter du texte ou un additionalContext structuré dans la conversation avant que Claude ne continue. Claude Code

Les hooks fonctionnent-ils avec les plugins/outils MCP ?
Oui—les plugins peuvent contribuer des hooks, et vous pouvez cibler les outils MCP via des matchers ; plusieurs hooks peuvent s'exécuter en parallèle pour un seul événement. Claude Code