Automatisieren Sie Workflows mit Hooks

​

Richten Sie Ihren ersten Hook ein

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

​

Was Sie automatisieren können

• Benachrichtigung erhalten, wenn Claude Eingaben benötigt
• Code nach Bearbeitungen automatisch formatieren
• Bearbeitungen geschützter Dateien blockieren
• Kontext nach Komprimierung erneut injizieren
• Konfigurationsänderungen prüfen
• Umgebung neu laden, wenn sich Verzeichnis oder Dateien ändern
• Bestimmte Berechtigungsaufforderungen automatisch genehmigen

​

Benachrichtigung erhalten, wenn Claude Eingaben benötigt

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

​

Code nach Bearbeitungen automatisch formatieren

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

​

Bearbeitungen geschützter Dateien blockieren

#!/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"
          }
        ]
      }
    ]
  }
}

​

Kontext nach Komprimierung erneut injizieren

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

​

Konfigurationsänderungen prüfen

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

​

Umgebung neu laden, wenn sich Verzeichnis oder Dateien ändern

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

​

Bestimmte Berechtigungsaufforderungen automatisch genehmigen

{
  "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" }
      ]
    }
  }
}

​

Wie Hooks funktionieren

• "type": "http": Event-Daten an eine URL POSTen. Siehe HTTP-Hooks.
• "type": "prompt": Single-Turn-LLM-Bewertung. Siehe Prompt-basierte Hooks.
• "type": "agent": Multi-Turn-Verifizierung mit Tool-Zugriff. Siehe Agent-basierte Hooks.

​

Eingabe lesen und Ausgabe zurückgeben

​

Hook-Eingabe

{
  "session_id": "abc123",          // eindeutige ID für diese Sitzung
  "cwd": "/Users/sarah/myproject", // Arbeitsverzeichnis, wenn das Event ausgelöst wurde
  "hook_event_name": "PreToolUse", // welches Event diesen Hook ausgelöst hat
  "tool_name": "Bash",             // das Tool, das Claude verwenden wird
  "tool_input": {                  // die Argumente, die Claude an das Tool übergeben hat
    "command": "npm test"          // für Bash ist dies der Shell-Befehl
  }
}

​

Hook-Ausgabe

#!/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 wird zu Claudes Feedback
  exit 2 # exit 2 = Aktion blockieren
fi

exit 0  # exit 0 = fortfahren

• Exit 0: die Aktion wird fortgesetzt. Für UserPromptSubmit- und SessionStart-Hooks wird alles, was Sie auf stdout schreiben, zu Claudes Kontext hinzugefügt.
• Exit 2: die Aktion wird blockiert. Schreiben Sie einen Grund auf stderr, und Claude erhält ihn als Feedback, sodass er sich anpassen kann.
• Jeder andere Exit-Code: die Aktion wird fortgesetzt. Stderr wird protokolliert, aber nicht Claude angezeigt. Schalten Sie den ausführlichen Modus mit Ctrl+O um, um diese Meldungen im Transkript zu sehen.

​

Strukturierte JSON-Ausgabe

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

• "allow": fortfahren, ohne eine Berechtigungsaufforderung anzuzeigen
• "deny": Tool-Aufruf abbrechen und den Grund an Claude senden
• "ask": Berechtigungsaufforderung dem Benutzer wie gewohnt anzeigen

​

Hooks mit Matchern filtern

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Hook-Speicherort konfigurieren

​

Prompt-basierte Hooks

• "ok": true: die Aktion wird fortgesetzt
• "ok": false: die Aktion wird blockiert. Der "reason" des Modells wird an Claude zurückgegeben, sodass es sich anpassen kann.

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

​

Agent-basierte Hooks

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

​

HTTP-Hooks

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

​

Einschränkungen und Fehlerbehebung

​

Einschränkungen

• Command-Hooks kommunizieren nur über stdout, stderr und Exit-Codes. Sie können Befehle oder Tool-Aufrufe nicht direkt auslösen. HTTP-Hooks kommunizieren stattdessen über den Response-Body.
• Hook-Timeout beträgt standardmäßig 10 Minuten, konfigurierbar pro Hook mit dem Feld timeout (in Sekunden).
• PostToolUse-Hooks können Aktionen nicht rückgängig machen, da das Tool bereits ausgeführt wurde.
• PermissionRequest-Hooks werden nicht im nicht-interaktiven Modus (-p) ausgelöst. Verwenden Sie stattdessen PreToolUse-Hooks für automatisierte Berechtigungsentscheidungen.
• Stop-Hooks werden ausgelöst, wenn Claude antwortet, nicht nur bei Aufgabenabschluss. Sie werden nicht bei Benutzerunterbrechungen ausgelöst. API-Fehler lösen stattdessen StopFailure aus.

​

Hook wird nicht ausgelöst

• Führen Sie /hooks aus und bestätigen Sie, dass der Hook unter dem richtigen Event angezeigt wird
• Überprüfen Sie, dass das Matcher-Muster den Tool-Namen genau abgleicht (Matcher sind Groß-/Kleinschreibung-empfindlich)
• Überprüfen Sie, dass Sie den richtigen Event-Typ auslösen (z. B. PreToolUse wird vor der Tool-Ausführung ausgelöst, PostToolUse wird danach ausgelöst)
• Wenn Sie PermissionRequest-Hooks im nicht-interaktiven Modus (-p) verwenden, wechseln Sie stattdessen zu PreToolUse

​

Hook-Fehler in der Ausgabe

• Ihr Skript wurde unerwartet mit einem Nicht-Null-Code beendet. Testen Sie es manuell, indem Sie Beispiel-JSON pipen:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Überprüfen Sie den Exit-Code
  
• Wenn Sie “command not found” sehen, verwenden Sie absolute Pfade oder $CLAUDE_PROJECT_DIR, um Skripte zu referenzieren
• Wenn Sie “jq: command not found” sehen, installieren Sie jq oder verwenden Sie Python/Node.js zum Parsen von JSON
• Wenn das Skript überhaupt nicht ausgeführt wird, machen Sie es ausführbar: chmod +x ./my-hook.sh

​

/hooks zeigt keine konfigurierten Hooks

• Datei-Bearbeitungen werden normalerweise automatisch aufgegriffen. Wenn sie nach ein paar Sekunden nicht angezeigt wurden, hat der Datei-Watcher die Änderung möglicherweise verpasst: Starten Sie Ihre Sitzung neu, um ein Neuladen zu erzwingen.
• Überprüfen Sie, dass Ihr JSON gültig ist (nachfolgende Kommas und Kommentare sind nicht zulässig)
• Bestätigen Sie, dass die Einstellungsdatei am richtigen Speicherort ist: .claude/settings.json für Projekt-Hooks, ~/.claude/settings.json für globale Hooks

​

Stop-Hook läuft endlos

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Erlauben Sie Claude zu stoppen
fi
# ... Rest Ihrer Hook-Logik

​

JSON-Validierung fehlgeschlagen

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

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

​

Debug-Techniken

​

Weitere Informationen

• Hooks-Referenz: vollständige Event-Schemas, JSON-Ausgabeformat, asynchrone Hooks und MCP-Tool-Hooks
• Sicherheitsüberlegungen: überprüfen Sie vor der Bereitstellung von Hooks in gemeinsamen oder Produktionsumgebungen
• Bash-Befehlsvalidator-Beispiel: vollständige Referenzimplementierung