Automatiser les workflows avec les hooks

​

Configurer votre premier hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Ce que vous pouvez automatiser

• Être notifié lorsque Claude a besoin d’une entrée
• Formater automatiquement le code après les modifications
• Bloquer les modifications des fichiers protégés
• Réinjecter le contexte après compaction
• Auditer les modifications de configuration
• Recharger l’environnement lorsque le répertoire ou les fichiers changent
• Approuver automatiquement les invites de permission spécifiques

​

Être notifié lorsque Claude a besoin d’une entrée

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formater automatiquement le code après les modifications

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Bloquer les modifications des fichiers protégés

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Réinjecter le contexte après compaction

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Auditer les modifications de configuration

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Recharger l’environnement lorsque le répertoire ou les fichiers changent

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Approuver automatiquement les invites de permission spécifiques

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Comment fonctionnent les hooks

• "type": "http" : POST les données d’événement vers une URL. Consultez Hooks HTTP.
• "type": "prompt" : évaluation LLM à un seul tour. Consultez Hooks basés sur des invites.
• "type": "agent" : vérification multi-tour avec accès aux outils. Les hooks d’agent sont expérimentaux et peuvent changer. Consultez Hooks basés sur des agents.

​

Lire l’entrée et retourner la sortie

​

Entrée du hook

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

​

Sortie du hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = let it proceed

• Exit 0 : l’action se poursuit. Pour les hooks UserPromptSubmit et SessionStart, tout ce que vous écrivez sur stdout est ajouté au contexte de Claude.
• Exit 2 : l’action est bloquée. Écrivez une raison sur stderr, et Claude la reçoit comme retour afin qu’il puisse s’ajuster.
• Tout autre code de sortie : l’action se poursuit. La transcription affiche un avis <hook name> hook error suivi de la première ligne de stderr ; le stderr complet va au journal de débogage.

​

Sortie JSON structurée

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow" : ignorer l’invite de permission interactive. Les règles de refus et d’ask, y compris les listes de refus gérées par l’entreprise, s’appliquent toujours
• "deny" : annuler l’appel d’outil et envoyer la raison à Claude
• "ask" : afficher l’invite de permission à l’utilisateur comme d’habitude

​

Filtrer les hooks avec des matchers

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Filtrer par nom d’outil et arguments avec le champ if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Configurer l’emplacement du hook

​

Hooks basés sur des invites

• "ok": true : l’action se poursuit
• "ok": false : l’action est bloquée. La "reason" du modèle est renvoyée à Claude afin qu’il puisse s’ajuster.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks basés sur des agents

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

Hooks HTTP

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitations et dépannage

​

Limitations

• Les hooks de commande communiquent uniquement via stdout, stderr et les codes de sortie. Ils ne peuvent pas déclencher directement des commandes / ou des appels d’outils. Le texte retourné via additionalContext est injecté comme un rappel système que Claude lit en tant que texte brut. Les hooks HTTP communiquent via le corps de la réponse à la place.
• Le délai d’expiration du hook est de 10 minutes par défaut, configurable par hook avec le champ timeout (en secondes).
• Les hooks PostToolUse ne peuvent pas annuler les actions puisque l’outil a déjà été exécuté.
• Les hooks PermissionRequest ne se déclenchent pas en mode non-interactif (-p). Utilisez les hooks PreToolUse pour les décisions de permission automatisées.
• Les hooks Stop se déclenchent chaque fois que Claude termine sa réponse, pas seulement à la fin de la tâche. Ils ne se déclenchent pas sur les interruptions de l’utilisateur. Les erreurs API déclenchent StopFailure à la place.
• Lorsque plusieurs hooks PreToolUse retournent updatedInput pour réécrire les arguments d’un outil, le dernier à terminer gagne. Puisque les hooks s’exécutent en parallèle, l’ordre est non-déterministe. Évitez d’avoir plus d’un hook modifier l’entrée du même outil.

​

Hooks et modes de permission

​

Hook ne se déclenche pas

• Exécutez /hooks et confirmez que le hook apparaît sous l’événement correct
• Vérifiez que le modèle de matcher correspond exactement au nom de l’outil (les matchers sont sensibles à la casse)
• Vérifiez que vous déclenchez le bon type d’événement (par exemple, PreToolUse se déclenche avant l’exécution de l’outil, PostToolUse se déclenche après)
• Si vous utilisez des hooks PermissionRequest en mode non-interactif (-p), passez à PreToolUse à la place

​

Erreur du hook dans la sortie

• Votre script a quitté avec un code non-zéro de manière inattendue. Testez-le manuellement en piping du JSON d’exemple :
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Si vous voyez « command not found », utilisez des chemins absolus ou $CLAUDE_PROJECT_DIR pour référencer les scripts
• Si vous voyez « jq: command not found », installez jq ou utilisez Python/Node.js pour l’analyse JSON
• Si le script ne s’exécute pas du tout, rendez-le exécutable : chmod +x ./my-hook.sh

​

/hooks n’affiche aucun hook configuré

• Les modifications de fichiers sont normalement récupérées automatiquement. Si elles n’ont pas apparues après quelques secondes, l’observateur de fichiers peut avoir manqué la modification : redémarrez votre session pour forcer un rechargement.
• Vérifiez que votre JSON est valide (les virgules finales et les commentaires ne sont pas autorisés)
• Confirmez que le fichier de paramètres est au bon emplacement : .claude/settings.json pour les hooks de projet, ~/.claude/settings.json pour les hooks globaux

​

Le hook Stop s’exécute indéfiniment

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

Validation JSON échouée

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Techniques de débogage

​

En savoir plus

• Référence des Hooks : schémas d’événements complets, format de sortie JSON, hooks asynchrones et hooks d’outils MCP
• Considérations de sécurité : examinez avant de déployer les hooks dans des environnements partagés ou de production
• Exemple de validateur de commande Bash : implémentation de référence complète