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

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

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

notify-send 'Claude Code' 'test'

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

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

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

• hook_event_name: das Event, das den Hook ausgelöst hat
• tool_name: das Tool, das Claude verwenden wird
• tool_input: die Argumente, die Claude an das Tool übergeben hat. Für Bash enthält sein command-Feld den Shell-Befehl.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

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 = keine Entscheidung; der normale Berechtigungsfluss gilt

• Exit 0: Ihr Hook meldet keinen Einwand über seinen Exit-Code.
  • Für einen PreToolUse-Hook genehmigt dies nicht den Tool-Aufruf: der normale Berechtigungsfluss gilt weiterhin.
  • Für UserPromptSubmit-, UserPromptExpansion-, SessionStart- und PostModelSwitch-Hooks fügt Claude Code stdout, das es als Klartext behandelt, zu Claudes Kontext hinzu.
• Exit 2: Claude Code blockiert die Aktion. Schreiben Sie einen Grund auf stderr. Wo er landet, hängt vom Event ab: Einige Events geben ihn an Claude als Feedback, damit es sich anpassen kann, andere zeigen ihn dem Benutzer, und einige, wie ConfigChange und Elicitation, zeigen keine Meldung. Einige Events können nicht blockiert werden: Für SessionStart 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: Für die meisten Events hängt das Ergebnis davon ab, was Ihr Hook auf stdout gedruckt hat:
  • Ein gepartes Objekt, das die Schema-Validierung besteht: Claude Code ignoriert den Exit-Code, nur das JSON entscheidet das Ergebnis, und der Hook wird nicht als Fehler gemeldet. Die Pro-Event-Ausnahmen, wie WorktreeCreate, das bei jedem Nonzero-Exit fehlschlägt, sind im Abschnitt Exit-Code-Ausgabe der Referenz aufgelistet.
  • Ein gepartes Objekt, das die Schema-Validierung nicht besteht, oder stdout, das Claude Code zu parsen versucht als JSON, aber das kein gültiges JSON ist: ein nicht blockierender Fehler; die Meldung enthält die Validierungs- oder Parse-Meldung.
  • Stdout, das Claude Code als Klartext behandelt, oder leeres stdout: die Aktion wird als nicht blockierender Fehler fortgesetzt. Das Transkript zeigt eine <hook name> hook error-Meldung, dann die erste Zeile von stderr mit dem Präfix Failed with non-blocking status code:. Um das vollständige stderr zu erfassen, aktivieren Sie Debug-Protokollierung mit claude --debug oder durch Ausführung von /debug während der Sitzung.

​

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, ebenso wie Aufforderungen für MCP-Tools, die mit requiresUserInteraction gekennzeichnet sind, und für Connector-Tools die Ihre Organisation auf ask gesetzt hat in Sitzungen, in denen diese Einstellung Claude Code erreicht
• "deny": Tool-Aufruf abbrechen und den Grund an Claude senden
• "ask": Berechtigungsaufforderung dem Benutzer wie gewohnt anzeigen

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

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, es sei denn, die Antwort setzt auch "impossible": true, um die Bedingung als eine zu kennzeichnen, die niemals erfüllt werden kann. In diesem Fall erlaubt Claude Code den Stop und der Zug endet
  • PreToolUse: der Tool-Aufruf wird verweigert; standardmäßig endet der Zug und der Ablehnungs-reason erscheint im Chat als Warnzeile. Setzen Sie continueOnBlock: true auf dem Hook, um stattdessen den reason an Claude als Tool-Fehler zurückzugeben, sodass es sich anpassen und fortfahren kann. Vor v2.1.210 wurde der Ablehnungs-reason an Claude als Tool-Fehler zurückgegeben und der Zug wurde fortgesetzt
  • PostToolUse: standardmäßig endet der Zug und der reason erscheint im Chat als Warnzeile. Setzen Sie continueOnBlock: true, um den reason an Claude zurückzugeben und den Zug stattdessen fortzusetzen
  • 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 keine /-Befehle oder Tool-Aufrufe auslösen. Text, der über additionalContext zurückgegeben wird, wird als Systemhinweis eingefügt, den 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. Claude Code senkt diesen Standard auf 30 Sekunden für UserPromptSubmit-, PreModelSwitch- und PostModelSwitch-Hooks und auf 10 Sekunden für MessageDisplay-Hooks.
  • prompt: 30 Sekunden.
  • agent: 60 Sekunden.
  • SessionEnd-Hooks aller Typen teilen sich ein Budget von 1,5 Sekunden. Wenn Ihre Einstellungen ein längeres timeout pro Hook setzen, erhöht Claude Code das Budget entsprechend, bis zu 60 Sekunden.
• PostToolUse-Hooks können Aktionen nicht rückgängig machen, da das Tool bereits ausgeführt wurde.
• PermissionRequest-Hooks werden ausgelöst, wenn Claude Code Sie um Genehmigung bitten möchte.
  • Im nicht-interaktiven Modus mit dem Flag -p existiert diese Eingabeaufforderung nur, wenn der canUseTool-Callback des Agent SDK sie bereitstellt. Bei einfachen -p-Läufen oder mit --permission-prompt-tool verwenden Sie stattdessen PreToolUse-Hooks für automatisierte Genehmigungsentscheidungen.
  • Hintergrund-Subagenten können im nicht-interaktiven Modus keine Eingabeaufforderung anzeigen. Claude Code führt die Hooks für ihre Tool-Aufrufe weiterhin aus, und wenn kein Hook eine Entscheidung zurückgibt, wird der Aufruf abgelehnt. In einer interaktiven Sitzung werden Eingabeaufforderungen von Hintergrund-Subagenten in Ihrer Hauptsitzung angezeigt und die Hooks werden wie gewohnt ausgelöst.
• Stop-Hooks werden ausgelöst, wenn Claude die Antwort beendet, nicht nur bei Aufgabenvollendung. 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, hat der zuletzt fertiggestellte Effekt. 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 Genehmigungsmodi

​

Hook wird nicht ausgelöst

• Führen Sie /hooks aus und bestätigen Sie, dass der Hook unter dem richtigen Ereignis angezeigt wird
• Überprüfen Sie, dass das Matcher-Muster den Tool-Namen genau entspricht. Matcher sind Groß-/Kleinschreibung-empfindlich
• Überprüfen Sie, dass Sie den richtigen Ereignistyp auslösen: PreToolUse wird vor der Tool-Ausführung ausgelöst, PostToolUse wird danach ausgelöst. Ein PermissionRequest-Hook wird ausgelöst, wenn Claude Code Sie um Genehmigung bitten möchte; siehe die Einschränkungen für die nicht-interaktiven Fälle

​

Hook-Fehler in der Ausgabe

• Ihr Skript wurde unerwartet mit einem Code ungleich Null beendet. Testen Sie es manuell, indem Sie Beispiel-JSON pipen:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Wenn Sie „command not found” sehen, verwenden Sie absolute Pfade oder ${CLAUDE_PROJECT_DIR}, um auf Skripte zu verweisen. Um Shell-Quoting ganz zu vermeiden, fügen Sie "args": [] hinzu, um zur Exec-Form zu wechseln, die das Skript direkt ohne Shell spawnt
• Wenn Sie „jq: command not found” sehen, installieren Sie jq oder verwenden Sie Python/Node.js für JSON-Parsing
• Wenn die Benachrichtigung eine JSON-Validierungsmeldung anzeigt, wurde die stdout Ihres Hooks als JSON geparst, aber die Schema-Validierung ist fehlgeschlagen. Wenn sie eine JSON-Parse-Meldung anzeigt, sah die stdout wie ein JSON-Objekt aus, war aber kein gültiges JSON. Beides passiert auch bei Exit 0. Um einen Parse-Fehler zu beheben, erstellen Sie die Payload mit einem JSON-Encoder wie jq statt String-Verkettung, damit Anführungszeichen und Backslashes in Werten escaped werden. Der Abschnitt Exit code output der Referenz behandelt die Exit-Code- und JSON-Kombinationen
• Wenn das Skript überhaupt nicht ausgeführt wird, machen Sie es ausführbar: chmod +x ./my-hook.sh

​

/hooks zeigt keine konfigurierten Hooks

• Dateibearbeitungen werden normalerweise automatisch aufgegriffen. Wenn sie nach einigen Sekunden nicht angezeigt werden, hat der Datei-Watcher die Änderung möglicherweise übersehen: 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 sich die Einstellungsdatei am richtigen Ort befindet: .claude/settings.json für Projekt-Hooks, ~/.claude/settings.json für globale Hooks

​

Stop Hook trifft die Block-Obergrenze

#!/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

​

Hook JSON hat keine Auswirkung

• Zusätzliche Ausgabe vor dem JSON: Etwas anderes schreibt zuerst zu stdout, normalerweise ein bedingungsloses echo in Ihrem Shell-Profil, sodass die Ausgabe nicht mehr mit { beginnt und Claude Code sie nicht als JSON parst. Die Ursache und Lösung folgen dieser Liste.
• Ein Feld auf der falschen Ebene: Vergleichen Sie die Platzierung jedes Feldes mit dem Format JSON output. Zum Beispiel gehört permissionDecision in hookSpecificOutput, nicht auf der obersten Ebene.

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

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

​

Debug-Techniken

• Erfolgreiche Ausführung: Sie sehen nichts, es sei denn, der Hook-JSON zeigt etwas an, wie systemMessage oder Stop Hook-Feedback.
  • Um zu bestätigen, dass ein Hook ausgeführt wurde, überprüfen Sie auf seine Auswirkung, wie eine umformatierte Datei, oder aktivieren Sie Debug-Protokollierung wie unten beschrieben und lösen Sie den Hook erneut aus
• Blockierender Fehler: Bei den meisten Ereignissen sehen Sie das Feedback des Hooks. Wenn das Hook-JSON eine blockierende Entscheidung getroffen hat, ist das Feedback der Grund aus dieser Entscheidung; andernfalls ist es der stderr des Hooks. Bei einigen Ereignissen, wie ConfigChange und Elicitation, wird ein Block nicht angezeigt.
• Nicht-blockierender Fehler: Die Aktion wurde fortgesetzt, und Sie sehen eine Benachrichtigung <hook name> hook error mit einer kurzen Erklärung, wie die erste Zeile von stderr mit dem Präfix Failed with non-blocking status code: oder eine JSON-Validierungs- oder Parse-Meldung.

​

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