Automatisieren Sie Workflows mit Hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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

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

​

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

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

​

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

​

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": "mcp_tool": ein Tool auf einem bereits verbundenen MCP-Server aufrufen. Siehe MCP-Tool-Hooks.
• "type": "prompt": Single-Turn-LLM-Bewertung. Siehe Prompt-basierte Hooks.
• "type": "agent": Multi-Turn-Verifizierung mit Tool-Zugriff. Agent-Hooks sind experimentell und können sich ändern. Siehe Agent-basierte Hooks.

​

Ergebnisse aus mehreren Hooks kombinieren

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

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, UserPromptExpansion 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. Einige Events können nicht blockiert werden: Für SessionStart, Setup, Notification und andere zeigt exit 2 stderr dem Benutzer an und die Ausführung wird fortgesetzt. Siehe Exit-Code-2-Verhalten pro Event für die vollständige Liste.
• Jeder andere Exit-Code: die Aktion wird fortgesetzt. Das Transkript zeigt eine <hook name> hook error-Meldung gefolgt von der ersten Zeile von stderr; das vollständige stderr geht in das Debug-Protokoll.

​

Strukturierte JSON-Ausgabe

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

• "allow": die interaktive Berechtigungsaufforderung überspringen. Deny- und Ask-Regeln, einschließlich verwalteter Deny-Listen, gelten weiterhin
• "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"
          }
        ]
      }
    ]
  }
}

​

Hooks mit dem Feld if nach Tool-Name und Argumenten filtern

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

​

Hook-Speicherort konfigurieren

​

Prompt-basierte Hooks

• "ok": true: die Aktion wird fortgesetzt
• "ok": false: was passiert, hängt vom Ereignis ab:
  • Stop und SubagentStop: der reason wird an Claude zurückgegeben, sodass es weiterarbeitet
  • PreToolUse: der Tool-Aufruf wird verweigert und der reason wird an Claude als Tool-Fehler zurückgegeben, sodass es sich anpassen und fortfahren kann
  • PostToolUse, PostToolBatch, UserPromptSubmit und UserPromptExpansion: der Zug endet und der reason erscheint im Chat als Warnzeile

{
  "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 auslösen. Text, der über additionalContext zurückgegeben wird, wird als Systemerinnerung injiziert, die Claude als Klartext liest. HTTP-Hooks kommunizieren stattdessen über den Response-Body.
• Hook-Timeouts variieren je nach Typ. Überschreiben Sie pro Hook mit dem Feld timeout in Sekunden.
  • command, http, mcp_tool: 10 Minuten. UserPromptSubmit reduziert diese auf 30 Sekunden.
  • prompt: 30 Sekunden.
  • agent: 60 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 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.
• Wenn mehrere PreToolUse-Hooks updatedInput zurückgeben, um die Argumente eines Tools umzuschreiben, gewinnt der letzte, der fertig wird. Da Hooks parallel ausgeführt werden, ist die Reihenfolge nicht deterministisch. Vermeiden Sie, dass mehr als ein Hook die Eingabe desselben Tools ändert.

​

Hooks und Berechtigungsmodi

​

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. Um Shell-Quoting vollständig zu vermeiden, fügen Sie "args": [] hinzu, um zur exec-Form zu wechseln, die das Skript direkt ohne eine Shell spawnt
• 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