Hooks-Referenz
Diese Seite bietet Referenzdokumentation für die Implementierung von Hooks in Claude Code.
Für eine Schnellstartanleitung mit Beispielen siehe Erste Schritte mit Claude Code Hooks.
Konfiguration
Claude Code Hooks werden in Ihren Einstellungsdateien konfiguriert:
~/.claude/settings.json
- Benutzereinstellungen.claude/settings.json
- Projekteinstellungen.claude/settings.local.json
- Lokale Projekteinstellungen (nicht committed)- Enterprise verwaltete Richtlinieneinstellungen
Struktur
Hooks sind nach Matchern organisiert, wobei jeder Matcher mehrere Hooks haben kann:
- matcher: Muster zum Abgleichen von Tool-Namen, groß-/kleinschreibungsabhängig (nur anwendbar für
PreToolUse
undPostToolUse
)- Einfache Strings stimmen exakt überein:
Write
stimmt nur mit dem Write-Tool überein - Unterstützt Regex:
Edit|Write
oderNotebook.*
- Verwenden Sie
*
um alle Tools zu matchen. Sie können auch einen leeren String (""
) verwenden odermatcher
leer lassen.
- Einfache Strings stimmen exakt überein:
- hooks: Array von Befehlen, die ausgeführt werden, wenn das Muster übereinstimmt
type
: Derzeit wird nur"command"
unterstütztcommand
: Der auszuführende Bash-Befehl (kann die Umgebungsvariable$CLAUDE_PROJECT_DIR
verwenden)timeout
: (Optional) Wie lange ein Befehl laufen soll, in Sekunden, bevor dieser spezifische Befehl abgebrochen wird.
Für Events wie UserPromptSubmit
, Notification
, Stop
und SubagentStop
,
die keine Matcher verwenden, können Sie das Matcher-Feld weglassen:
Projektspezifische Hook-Skripte
Sie können die Umgebungsvariable CLAUDE_PROJECT_DIR
(nur verfügbar, wenn
Claude Code den Hook-Befehl spawnt) verwenden, um auf in Ihrem Projekt gespeicherte Skripte zu verweisen,
wodurch sichergestellt wird, dass sie unabhängig von Claudes aktuellem Verzeichnis funktionieren:
Hook-Events
PreToolUse
Läuft nachdem Claude Tool-Parameter erstellt hat und vor der Verarbeitung des Tool-Aufrufs.
Häufige Matcher:
Task
- Subagent-Aufgaben (siehe Subagents-Dokumentation)Bash
- Shell-BefehleGlob
- Dateimuster-AbgleichGrep
- InhaltssucheRead
- Datei lesenEdit
,MultiEdit
- Datei bearbeitenWrite
- Datei schreibenWebFetch
,WebSearch
- Web-Operationen
PostToolUse
Läuft unmittelbar nachdem ein Tool erfolgreich abgeschlossen wurde.
Erkennt dieselben Matcher-Werte wie PreToolUse.
Notification
Läuft wenn Claude Code Benachrichtigungen sendet. Benachrichtigungen werden gesendet wenn:
- Claude Ihre Erlaubnis benötigt, um ein Tool zu verwenden. Beispiel: “Claude needs your permission to use Bash”
- Die Prompt-Eingabe mindestens 60 Sekunden inaktiv war. “Claude is waiting for your input”
UserPromptSubmit
Läuft wenn der Benutzer einen Prompt einreicht, bevor Claude ihn verarbeitet. Dies ermöglicht es Ihnen, zusätzlichen Kontext basierend auf dem Prompt/der Unterhaltung hinzuzufügen, Prompts zu validieren oder bestimmte Arten von Prompts zu blockieren.
Stop
Läuft wenn der Haupt-Claude Code Agent seine Antwort beendet hat. Läuft nicht, wenn die Unterbrechung aufgrund einer Benutzerunterbrechung erfolgte.
SubagentStop
Läuft wenn ein Claude Code Subagent (Task-Tool-Aufruf) seine Antwort beendet hat.
SessionEnd
Läuft wenn eine Claude Code Sitzung endet. Nützlich für Aufräumaufgaben, Protokollierung von Sitzungsstatistiken oder Speichern des Sitzungsstatus.
Das reason
-Feld in der Hook-Eingabe wird eines der folgenden sein:
clear
- Sitzung mit /clear-Befehl gelöschtlogout
- Benutzer hat sich abgemeldetprompt_input_exit
- Benutzer ist ausgestiegen, während die Prompt-Eingabe sichtbar warother
- Andere Ausstiegsgründe
PreCompact
Läuft bevor Claude Code eine Compact-Operation ausführen wird.
Matcher:
manual
- Aufgerufen von/compact
auto
- Aufgerufen von Auto-Compact (aufgrund eines vollen Kontextfensters)
SessionStart
Läuft wenn Claude Code eine neue Sitzung startet oder eine bestehende Sitzung fortsetzt (was derzeit unter der Haube eine neue Sitzung startet). Nützlich zum Laden von Entwicklungskontext wie bestehende Issues oder kürzliche Änderungen an Ihrer Codebasis.
Matcher:
startup
- Aufgerufen beim Startupresume
- Aufgerufen von--resume
,--continue
oder/resume
clear
- Aufgerufen von/clear
Hook-Eingabe
Hooks erhalten JSON-Daten über stdin, die Sitzungsinformationen und event-spezifische Daten enthalten:
PreToolUse-Eingabe
Das genaue Schema für tool_input
hängt vom Tool ab.
PostToolUse-Eingabe
Das genaue Schema für tool_input
und tool_response
hängt vom Tool ab.
Notification-Eingabe
UserPromptSubmit-Eingabe
Stop- und SubagentStop-Eingabe
stop_hook_active
ist true, wenn Claude Code bereits als Ergebnis eines
Stop-Hooks fortsetzt. Überprüfen Sie diesen Wert oder verarbeiten Sie das Transkript, um zu verhindern, dass Claude Code
unendlich läuft.
PreCompact-Eingabe
Für manual
kommt custom_instructions
von dem, was der Benutzer in
/compact
übergibt. Für auto
ist custom_instructions
leer.
SessionStart-Eingabe
SessionEnd-Eingabe
Hook-Ausgabe
Es gibt zwei Möglichkeiten für Hooks, Ausgaben an Claude Code zurückzugeben. Die Ausgabe kommuniziert, ob blockiert werden soll und welches Feedback Claude und dem Benutzer gezeigt werden soll.
Einfach: Exit-Code
Hooks kommunizieren Status über Exit-Codes, stdout und stderr:
- Exit-Code 0: Erfolg.
stdout
wird dem Benutzer im Transkript-Modus gezeigt (CTRL-R), außer fürUserPromptSubmit
undSessionStart
, wo stdout zum Kontext hinzugefügt wird. - Exit-Code 2: Blockierender Fehler.
stderr
wird an Claude zurückgegeben, um automatisch verarbeitet zu werden. Siehe Verhalten pro Hook-Event unten. - Andere Exit-Codes: Nicht-blockierender Fehler.
stderr
wird dem Benutzer gezeigt und die Ausführung wird fortgesetzt.
Erinnerung: Claude Code sieht stdout nicht, wenn der Exit-Code 0 ist, außer für
den UserPromptSubmit
-Hook, wo stdout als Kontext injiziert wird.
Exit-Code 2 Verhalten
Hook Event | Verhalten |
---|---|
PreToolUse | Blockiert den Tool-Aufruf, zeigt stderr Claude |
PostToolUse | Zeigt stderr Claude (Tool ist bereits gelaufen) |
Notification | N/A, zeigt stderr nur dem Benutzer |
UserPromptSubmit | Blockiert Prompt-Verarbeitung, löscht Prompt, zeigt stderr nur dem Benutzer |
Stop | Blockiert Stopp, zeigt stderr Claude |
SubagentStop | Blockiert Stopp, zeigt stderr Claude Subagent |
PreCompact | N/A, zeigt stderr nur dem Benutzer |
SessionStart | N/A, zeigt stderr nur dem Benutzer |
SessionEnd | N/A, zeigt stderr nur dem Benutzer |
Erweitert: JSON-Ausgabe
Hooks können strukturiertes JSON in stdout
für anspruchsvollere Kontrolle zurückgeben:
Gemeinsame JSON-Felder
Alle Hook-Typen können diese optionalen Felder enthalten:
Wenn continue
false ist, stoppt Claude die Verarbeitung nach dem Ausführen der Hooks.
- Für
PreToolUse
ist dies anders als"permissionDecision": "deny"
, was nur einen spezifischen Tool-Aufruf blockiert und automatisches Feedback an Claude liefert. - Für
PostToolUse
ist dies anders als"decision": "block"
, was automatisiertes Feedback an Claude liefert. - Für
UserPromptSubmit
verhindert dies, dass der Prompt verarbeitet wird. - Für
Stop
undSubagentStop
hat dies Vorrang vor jeder"decision": "block"
-Ausgabe. - In allen Fällen hat
"continue" = false
Vorrang vor jeder"decision": "block"
-Ausgabe.
stopReason
begleitet continue
mit einem Grund, der dem Benutzer gezeigt wird, nicht
Claude gezeigt wird.
PreToolUse
Entscheidungskontrolle
PreToolUse
-Hooks können kontrollieren, ob ein Tool-Aufruf fortgesetzt wird.
"allow"
umgeht das Berechtigungssystem.permissionDecisionReason
wird dem Benutzer gezeigt, aber nicht Claude."deny"
verhindert, dass der Tool-Aufruf ausgeführt wird.permissionDecisionReason
wird Claude gezeigt."ask"
bittet den Benutzer, den Tool-Aufruf in der UI zu bestätigen.permissionDecisionReason
wird dem Benutzer gezeigt, aber nicht Claude.
Die Felder decision
und reason
sind für PreToolUse-Hooks veraltet.
Verwenden Sie stattdessen hookSpecificOutput.permissionDecision
und
hookSpecificOutput.permissionDecisionReason
. Die veralteten Felder
"approve"
und "block"
werden auf "allow"
bzw. "deny"
abgebildet.
PostToolUse
Entscheidungskontrolle
PostToolUse
-Hooks können nach Tool-Ausführung Feedback an Claude liefern.
"block"
fordert Claude automatisch mitreason
auf.undefined
tut nichts.reason
wird ignoriert."hookSpecificOutput.additionalContext"
fügt Kontext für Claude hinzu.
UserPromptSubmit
Entscheidungskontrolle
UserPromptSubmit
-Hooks können kontrollieren, ob ein Benutzer-Prompt verarbeitet wird.
"block"
verhindert, dass der Prompt verarbeitet wird. Der eingereichte Prompt wird aus dem Kontext gelöscht."reason"
wird dem Benutzer gezeigt, aber nicht zum Kontext hinzugefügt.undefined
erlaubt dem Prompt, normal fortzufahren."reason"
wird ignoriert."hookSpecificOutput.additionalContext"
fügt den String zum Kontext hinzu, wenn nicht blockiert.
Stop
/SubagentStop
Entscheidungskontrolle
Stop
- und SubagentStop
-Hooks können kontrollieren, ob Claude fortfahren muss.
"block"
verhindert, dass Claude stoppt. Sie müssenreason
für Claude ausfüllen, damit er weiß, wie er fortfahren soll.undefined
erlaubt Claude zu stoppen.reason
wird ignoriert.
SessionStart
Entscheidungskontrolle
SessionStart
-Hooks ermöglichen es Ihnen, Kontext zu Beginn einer Sitzung zu laden.
"hookSpecificOutput.additionalContext"
fügt den String zum Kontext hinzu.- Mehrere Hooks’
additionalContext
-Werte werden verkettet.
SessionEnd
Entscheidungskontrolle
SessionEnd
-Hooks laufen, wenn eine Sitzung endet. Sie können die Sitzungsbeendigung nicht blockieren,
aber Aufräumaufgaben durchführen.
Exit-Code Beispiel: Bash-Befehl-Validierung
JSON-Ausgabe Beispiel: UserPromptSubmit zum Hinzufügen von Kontext und Validierung
Für UserPromptSubmit
-Hooks können Sie Kontext mit beiden Methoden injizieren:
- Exit-Code 0 mit stdout: Claude sieht den Kontext (Sonderfall für
UserPromptSubmit
) - JSON-Ausgabe: Bietet mehr Kontrolle über das Verhalten
JSON-Ausgabe Beispiel: PreToolUse mit Genehmigung
Arbeiten mit MCP-Tools
Claude Code Hooks funktionieren nahtlos mit Model Context Protocol (MCP) Tools. Wenn MCP-Server Tools bereitstellen, erscheinen sie mit einem speziellen Benennungsmuster, das Sie in Ihren Hooks matchen können.
MCP-Tool-Benennung
MCP-Tools folgen dem Muster mcp__<server>__<tool>
, zum Beispiel:
mcp__memory__create_entities
- Memory-Server’s Create-Entities-Toolmcp__filesystem__read_file
- Filesystem-Server’s Read-File-Toolmcp__github__search_repositories
- GitHub-Server’s Search-Tool
Konfigurieren von Hooks für MCP-Tools
Sie können spezifische MCP-Tools oder ganze MCP-Server anvisieren:
Beispiele
Für praktische Beispiele einschließlich Code-Formatierung, Benachrichtigungen und Dateischutz siehe Weitere Beispiele in der Erste-Schritte-Anleitung.
Sicherheitsüberlegungen
Haftungsausschluss
VERWENDUNG AUF EIGENE GEFAHR: Claude Code Hooks führen beliebige Shell-Befehle auf Ihrem System automatisch aus. Durch die Verwendung von Hooks erkennen Sie an, dass:
- Sie sind allein verantwortlich für die Befehle, die Sie konfigurieren
- Hooks können alle Dateien ändern, löschen oder darauf zugreifen, auf die Ihr Benutzerkonto zugreifen kann
- Bösartige oder schlecht geschriebene Hooks können Datenverlust oder Systemschäden verursachen
- Anthropic bietet keine Garantie und übernimmt keine Haftung für Schäden, die aus der Hook-Verwendung resultieren
- Sie sollten Hooks gründlich in einer sicheren Umgebung testen, bevor Sie sie produktiv verwenden
Überprüfen und verstehen Sie immer alle Hook-Befehle, bevor Sie sie zu Ihrer Konfiguration hinzufügen.
Sicherheits-Best-Practices
Hier sind einige wichtige Praktiken zum Schreiben sichererer Hooks:
- Eingaben validieren und bereinigen - Vertrauen Sie niemals blind Eingabedaten
- Shell-Variablen immer in Anführungszeichen setzen - Verwenden Sie
"$VAR"
nicht$VAR
- Pfad-Traversal blockieren - Prüfen Sie auf
..
in Dateipfaden - Absolute Pfade verwenden - Geben Sie vollständige Pfade für Skripte an (verwenden Sie
$CLAUDE_PROJECT_DIR
für den Projektpfad) - Sensible Dateien überspringen - Vermeiden Sie
.env
,.git/
, Schlüssel, etc.
Konfigurationssicherheit
Direkte Bearbeitungen von Hooks in Einstellungsdateien werden nicht sofort wirksam. Claude Code:
- Erfasst einen Snapshot von Hooks beim Start
- Verwendet diesen Snapshot während der gesamten Sitzung
- Warnt, wenn Hooks extern geändert werden
- Erfordert Überprüfung im
/hooks
-Menü, damit Änderungen angewendet werden
Dies verhindert, dass bösartige Hook-Änderungen Ihre aktuelle Sitzung beeinträchtigen.
Hook-Ausführungsdetails
- Timeout: 60-Sekunden-Ausführungslimit standardmäßig, pro Befehl konfigurierbar.
- Ein Timeout für einen einzelnen Befehl beeinflusst die anderen Befehle nicht.
- Parallelisierung: Alle passenden Hooks laufen parallel
- Deduplizierung: Mehrere identische Hook-Befehle werden automatisch dedupliziert
- Umgebung: Läuft im aktuellen Verzeichnis mit Claude Codes Umgebung
- Die Umgebungsvariable
CLAUDE_PROJECT_DIR
ist verfügbar und enthält den absoluten Pfad zum Projekt-Root-Verzeichnis (wo Claude Code gestartet wurde)
- Die Umgebungsvariable
- Eingabe: JSON über stdin
- Ausgabe:
- PreToolUse/PostToolUse/Stop/SubagentStop: Fortschritt im Transkript gezeigt (Ctrl-R)
- Notification/SessionEnd: Nur in Debug protokolliert (
--debug
) - UserPromptSubmit/SessionStart: stdout als Kontext für Claude hinzugefügt
Debugging
Grundlegende Fehlerbehebung
Wenn Ihre Hooks nicht funktionieren:
- Konfiguration prüfen - Führen Sie
/hooks
aus, um zu sehen, ob Ihr Hook registriert ist - Syntax überprüfen - Stellen Sie sicher, dass Ihre JSON-Einstellungen gültig sind
- Befehle testen - Führen Sie Hook-Befehle zuerst manuell aus
- Berechtigungen prüfen - Stellen Sie sicher, dass Skripte ausführbar sind
- Logs überprüfen - Verwenden Sie
claude --debug
, um Hook-Ausführungsdetails zu sehen
Häufige Probleme:
- Anführungszeichen nicht escaped - Verwenden Sie
\"
innerhalb von JSON-Strings - Falscher Matcher - Prüfen Sie, ob Tool-Namen exakt übereinstimmen (groß-/kleinschreibungsabhängig)
- Befehl nicht gefunden - Verwenden Sie vollständige Pfade für Skripte
Erweiterte Fehlerbehebung
Für komplexe Hook-Probleme:
- Hook-Ausführung inspizieren - Verwenden Sie
claude --debug
, um detaillierte Hook- Ausführung zu sehen - JSON-Schemas validieren - Testen Sie Hook-Ein-/Ausgabe mit externen Tools
- Umgebungsvariablen prüfen - Überprüfen Sie, ob Claude Codes Umgebung korrekt ist
- Edge-Cases testen - Probieren Sie Hooks mit ungewöhnlichen Dateipfaden oder Eingaben
- Systemressourcen überwachen - Prüfen Sie auf Ressourcenerschöpfung während Hook- Ausführung
- Strukturierte Protokollierung verwenden - Implementieren Sie Protokollierung in Ihren Hook-Skripten
Debug-Ausgabe Beispiel
Verwenden Sie claude --debug
, um Hook-Ausführungsdetails zu sehen:
Fortschrittsmeldungen erscheinen im Transkript-Modus (Ctrl-R) und zeigen:
- Welcher Hook läuft
- Befehl, der ausgeführt wird
- Erfolg-/Fehlerstatus
- Ausgabe- oder Fehlermeldungen