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\"'"
          }
        ]
      }
    ]
  }
}

​

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\"'"
          }
        ]
      }
    ]
  }
}

{
  "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": {
    "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. 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. Stderr est enregistré mais non affiché à Claude. Basculez le mode verbeux avec Ctrl+O pour voir ces messages dans la transcription.

​

Sortie JSON structurée

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

• "allow" : procéder sans afficher une invite de permission
• "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"
          }
        ]
      }
    ]
  }
}

​

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. 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.

​

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