Kurze Zusammenfassung: Claude Code Hooks sind Automatisierungsskripte, die zu bestimmten Zeitpunkten im Lebenszyklus von KI-Codingsitzungen ausgeführt werden und es Entwicklern ermöglichen, benutzerdefinierte Befehle auszuführen, Aktionen zu validieren, Code zu formatieren, Benachrichtigungen zu senden und Projektregeln durchzusetzen. Diese Hooks integrieren sich in den Workflow von Claude über Ereignisse wie SessionStart, PreToolUse und PostToolUse und unterstützen befehlsbasierte, HTTP-basierte und Prompt-basierte Ausführungsmuster mit konfigurierbaren Timeouts und Exit-Code-Verhalten.
Das Hook-System von Claude Code verwandelt den KI-Coding-Assistenten von einem hilfreichen Werkzeug in eine vollautomatisierte Entwicklungsumgebung. Die meisten Entwickler erkennen nicht das Ausmaß der Kontrolle, die durch Hooks verfügbar ist.
Die Sache ist jedoch: Hooks dienen nicht nur zum Ausführen von Skripten nach Dateiänderungen. Sie bieten Abfangpunkte während des gesamten Entscheidungsprozesses von Claude. Bevor er einen Befehl ausführt. Nachdem ein Toolaufruf fehlgeschlagen ist. Wenn er um Erlaubnis bittet. Sogar bevor Benutzer-Prompts verarbeitet werden.
Diese Anleitung deckt alles ab, was die offizielle Dokumentation bietet, sowie praktische Muster, die sich in Community-Diskussionen als tatsächlich produktionsreif erwiesen haben.
Was Claude Code Hooks tatsächlich tun
Laut der offiziellen Claude Code-Dokumentation sind Hooks benutzerdefinierte Shell-Befehle, HTTP-Endpunkte oder Prompt-Injektionen, die zu bestimmten Zeitpunkten im Lebenszyklus von Claude Code ausgeführt werden. Sie empfangen strukturierte JSON-Eingaben über stdin und steuern den Workflow über Exit-Codes oder HTTP-Antworten.
Die Automatisierung geht tiefer, als die meisten Anleitungen suggerieren. Hooks können die Toolausführung vollständig blockieren, Claude's Logik mit zusätzlichem Kontext anreichern, externe Dienste auslösen und Validierungsregeln durchsetzen, die Claude respektieren muss.
Es gibt drei Haupt-Hook-Typen:
- Befehlshooks: Shell-Skripte, die über stdout, stderr und Exit-Codes kommunizieren
- HTTP-Hooks: Remote-Endpunkte, die POST-Anfragen empfangen und JSON-Antworten zurückgeben
- Prompt-Hooks: Dynamische Anweisungen, die zu bestimmten Ereignissen in Claude's Kontext injiziert werden
Jeder Typ dient unterschiedlichen Automatisierungsmustern. Befehlshooks behandeln lokale Validierung und Formatierung. HTTP-Hooks integrieren sich in externe Dienste und Datenbanken. Prompt-Hooks modifizieren das Verhalten von Claude ohne externe Prozesse.
Hook-Lebenszyklus und Ereignissystem
Die offizielle Dokumentation definiert mehrere Hook-Ereignisse (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification und andere), die während des Ausführungsflusses von Claude Code ausgelöst werden. Das Verständnis, wann jedes einzelne ausgelöst wird, bestimmt, welche Automatisierung möglich ist.
| Event | Wann es ausgelöst wird | Kann blockieren |
|---|---|---|
| SessionStart | Wenn eine Sitzung beginnt oder fortgesetzt wird | Nein |
| UserPromptSubmit | Wenn Sie einen Prompt übermitteln, bevor Claude ihn verarbeitet | Ja |
| PreToolUse | Bevor ein Toolaufruf ausgeführt wird | Ja |
| PermissionRequest | Wenn ein Berechtigungsdialog erscheint | Ja |
| PostToolUse | Nachdem ein Toolaufruf erfolgreich war | Nein |
| PostToolUseFailure | Nachdem ein Toolaufruf fehlgeschlagen ist | Nein |
| Notification | Wenn Claude Code eine Benachrichtigung sendet | Nein |
| SubmitMessage | Wenn Claude eine Nachricht an den Benutzer sendet | Nein |
| ContextCompaction | Wenn sich das Kontextfenster den Grenzen nähert | Nein |
Die Blockierfähigkeit ist am wichtigsten. PreToolUse-Hooks können gefährliche Operationen verhindern, bevor sie ausgeführt werden. Exit-Code 1 blockiert die Aktion. Exit-Code 0 erlaubt sie. Exit-Code 2 fordert Claude auf, neu zu überdenken.
Aber warten Sie. PostToolUse-Hooks können Aktionen nicht rückgängig machen, da das Tool bereits ausgeführt wurde. Diese Einschränkung prägt die Struktur der Validierungslogik. Kritische Prüfungen gehören in PreToolUse. Aufräumarbeiten und Formatierung gehören in PostToolUse.
AI-Tool-Vorteile anzeigen, während Claude Code eingerichtet wird
Wenn Sie mit Claude Code Hooks arbeiten, wählen Sie möglicherweise auch andere KI-Tools in Ihrem Workflow aus. Get AI Perks sammelt Startup-Credits und Software-Rabatte für KI- und Cloud-Tools an einem Ort. Die Plattform umfasst über 200 Angebote mit Perk-Bedingungen und Beanspruchungsanleitungen für jedes einzelne.
Suchen Sie Claude oder andere KI-Tool-Vorteile?
Überprüfen Sie Get AI Perks, um:
- Claude und andere KI-Tool-Angebote durchsuchen
- Perk-Bedingungen vor der Bewerbung vergleichen
- Startup-Rabatte über Ihren Tool-Stack hinweg finden
👉 Besuchen Sie Get AI Perks, um aktuelle KI-Software-Vorteile zu erkunden.
Konfiguration und Dateistruktur
Hooks werden in der Datei .claude/settings.json innerhalb eines Projekts definiert. Das Konfigurationsschema unterstützt globale Hooks und tool-spezifische Matcher, die filtern, wann Hooks ausgeführt werden.
Grundlegende Befehlshook-Struktur:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Die Variable ${file} wird zum tatsächlichen Dateipfad aus der Tool-Eingabe erweitert. Laut der offiziellen Dokumentation unterstützen Hooks diese Variablenerweiterungen in den Feldern command und args.
Hook-Standorthierarchie
Claude Code prüft mehrere Orte auf Hook-Definitionen, mit einer klaren Reihenfolge der Priorität:
- Projekt-Ebene: .claude/settings.json im aktuellen Arbeitsbereich
- Benutzer-Ebene: ~/.claude/settings.json für alle Sitzungen
- Von Plugins bereitgestellt: Hooks, die mit installierten Plugins gebündelt sind
Projekt-Hooks überschreiben Benutzer-Hooks für dasselbe Ereignis. Dies ermöglicht projektspezifische Formatierungsregeln, während globale Benachrichtigungs-Handler beibehalten werden.
Matcher-Muster für selektive Ausführung
Das Matcher-System filtert Hooks für spezifische Tools oder Bedingungen. Ohne Matcher werden Hooks für jedes Vorkommen ihres Ereignisses ausgelöst.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Das Feld pathPattern akzeptiert Glob-Syntax. Das Feld toolName gleicht mit den integrierten Tools von Claude wie edit_file, execute_command, read_file und create_directory ab.
Community-Diskussionen zeigen, dass Matcher-Kombinationen mit AND-Logik funktionieren. Alle angegebenen Matcher müssen übereinstimmen, damit der Hook ausgeführt wird.
Befehlshooks: Shell-Skript-Integration
Befehlshooks führen Shell-Befehle oder Skripte mit strukturierter JSON-Eingabe aus. Sie stellen die häufigste Hook-Art für lokale Automatisierung dar.
Die offizielle Dokumentation besagt, dass Befehlshooks JSON über stdin mit dieser Struktur empfangen:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripte parsen diese Eingabe, um Entscheidungen zu treffen. Ein Python-Validierungs-Hook könnte so aussehen:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Exit-Code 0 erlaubt die Operation. Exit-Code 1 blockiert sie und zeigt die stderr-Nachricht an Claude an. Exit-Code 2 löst je nach Ereignis ein besonderes Verhalten aus.
Verhalten von Exit-Code 2
Laut der offiziellen Referenzdokumentation für Hooks hat Exit-Code 2 eine ereignisspezifische Bedeutung (PreToolUse: blockiert und fordert zur Überprüfung auf; UserPromptSubmit: stellt Kontext bereit, ohne zu blockieren; PermissionRequest: blockiert die Erlaubnis):
- PreToolUse: Blockiert das Tool und fordert Claude auf, mit der stderr-Nachricht als Kontext erneut zu prüfen
- UserPromptSubmit: Stellt die stderr-Ausgabe als zusätzlichen Kontext bereit, ohne zu blockieren
- PermissionRequest: Blockiert die Gewährung der Erlaubnis
Dies schafft eine Zwischenlösung zwischen harter Blockade und Erlaubnis. Claude erhält Feedback darüber, warum die Aktion problematisch sein könnte, und kann seinen Ansatz anpassen.
Asynchrone Befehlshooks
Das Flag async: true führt Hooks im Hintergrund aus, ohne den Workflow von Claude zu blockieren. Dies ist wichtig für langsame Operationen wie Bereitstellungsbenachrichtigungen oder Metriksammlungen.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Wenn ein asynchroner Hook ausgelöst wird, startet Claude Code den Prozess und fährt sofort fort. Das Feld timeout legt die maximale Ausführungszeit in Sekunden fest. Wenn nicht angegeben, verwenden asynchrone Hooks einen Standard-Timeout von 10 Minuten.
Ehrlich gesagt: Asynchrone Hooks können keine Operationen blockieren, da sie ausgeführt werden, nachdem Claude fortfährt. Sie eignen sich für Protokollierung, Benachrichtigungen und Bereinigung – nicht für Validierung.
HTTP-Hooks: Integration externer Dienste
HTTP-Hooks senden JSON-Payloads an Remote-Endpunkte und parsen Antworten zur Entscheidungssteuerung. Sie ermöglichen die Integration mit Validierungsdiensten, Datenbanken und Drittanbieter-Tools.
Grundlegende Konfiguration für HTTP-Hooks:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Die Payload-Struktur entspricht der Eingabe für Befehlshooks, kommt aber als HTTP-POST-Body an. Die Antwort bestimmt die nächste Aktion von Claude.
Verarbeitung von HTTP-Antworten
Laut der offiziellen Dokumentation interpretieren HTTP-Hooks Antworten basierend auf dem Statuscode und dem Body-Inhalt:
| Statuscode | Effekt | Nachrichtenquelle |
|---|---|---|
| 200 | Operation zulassen | Antwort-Body (optional) |
| 400 | Operation blockieren | Antwort-Body wird Claude angezeigt |
| 500 | Hook-Fehler, Operation zulassen | Protokolliert, aber Claude nicht angezeigt |
| Andere | Operation zulassen | Hook-Fehler blockiert den Workflow nicht |
Der Antwort-Body kann ein Nachrichtenfeld enthalten, das Claude als Kontext sieht. Dies ermöglicht es Validierungsdiensten zu erklären, warum eine Operation blockiert wurde.
Umgebungsvariablen-Interpolation
HTTP-Hooks unterstützen die Syntax ${VAR} in url, headers und anderen String-Feldern. Variablen werden aus der Umgebung erweitert, in der Claude Code ausgeführt wird.
Laut der offiziellen MCP-Dokumentation beinhaltet die Erweiterung von Umgebungsvariablen eine Standard-Fallback-Syntax: ${VAR:-default} wird zu VAR erweitert, wenn es gesetzt ist, andernfalls wird der Standardwert verwendet.
Sicherheitsbeschränkung: Laut GitHub-Issue #28044 können HTTP-Hooks nur auf Umgebungsvariablen zugreifen, die explizit im Konfigurationsfeld allowedEnvVars aufgeführt sind. Dies verhindert eine versehentliche Offenlegung von Anmeldeinformationen.
Prompt-Hooks: Kontextinjektion
Prompt-Hooks injizieren dynamische Anweisungen in Claude's Kontext zu bestimmten Ereignissen. Sie ändern das Verhalten ohne externe Prozesse oder API-Aufrufe.
| { “event”: “SessionStart”, “prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.” } |
Der injizierte Text wird Teil der Systemanweisungen von Claude für diese Sitzung. Prompt-Hooks können auch Vorlagenvariablen verwenden, die basierend auf den Ereignisdaten erweitert werden.
Dynamische Prompt-Generierung
Laut der offiziellen Dokumentation unterstützen Prompt-Hooks Befehlsfelder, die dynamische Prompts generieren:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Der Befehl empfängt die Standard-JSON-Eingabe über stdin und gibt den Prompt-Text an stdout aus. Dies ermöglicht die Generierung von kontextbezogenen Anweisungen basierend auf dem Projektzustand.
Agentenbasierte Hooks
Agent-Hooks geben einen Subagenten an, der das Ereignis anstelle einer direkten Prompt-Injektion behandelt. Der Subagent erhält Kontext über das Ereignis und kann mehrstufige Logik durchführen.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.” } |
Der benannte Subagent muss in der Projektkonfiguration definiert sein. Agent-Hooks ermöglichen komplexe Entscheidungslogik, die einfache Prompt-Injektion nicht bieten kann.
Praktische Hook-Muster
Community-Diskussionen und offizielle Beispiele zeigen spezifische Automatisierungsmuster, die in Produktionsumgebungen zuverlässig funktionieren.
Code nach Bearbeitungen automatisch formatieren
Das häufigste Muster formatiert Code automatisch, nachdem Claude Dateien bearbeitet hat:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Die Variable ${toolInput.path} wird zum Pfad der bearbeiteten Datei erweitert. PostToolUse stellt sicher, dass die Formatierung nach erfolgreichen Bearbeitungen erfolgt, blockiert aber nicht den Workflow von Claude.
Änderungen an geschützten Dateien blockieren
PreToolUse-Hooks erzwingen Regeln für den Dateischutz:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Das Skript validiert den Zielpfad anhand von geschützten Mustern und wird mit dem Code 1 beendet, um verbotene Bearbeitungen zu blockieren.
Benachrichtigung erhalten, wenn Claude Eingaben benötigt
Laut der offiziellen Workflow-Anleitung können Notification-Hooks Desktop-Benachrichtigungen auslösen oder Nachrichten an externe Dienste senden:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Dies wird jedes Mal ausgelöst, wenn Claude Code eine Benachrichtigung sendet, einschließlich Wartezeiten auf Benutzereingaben oder nach Abschluss einer Aufgabe.
Kontext nach Verdichtung erneut injizieren
ContextCompaction-Hooks stellen wichtigen Kontext wieder her, wenn das Gesprächsfenster voll wird:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Die Befehlsausgabe wird wieder in Claude's Kontext injiziert, nachdem die Verdichtung ältere Nachrichten entfernt hat. Dies verhindert den Verlust von kritischen projektspezifischen Anweisungen.
Konfigurationsänderungen protokollieren
Verfolgen Sie, wann Claude Konfigurationsdateien ändert:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asynchrone Ausführung verhindert die Blockierung von Claude, während Git-Operationen abgeschlossen werden. Dies schafft eine Audit-Spur von Konfigurationsänderungen ohne manuelle Staging.
JSON-Ausgabe und Entscheidungssteuerung
Befehlshooks können strukturierte JSON-Ausgaben erzeugen, um detailliertes Feedback über einfache Exit-Codes hinaus zu liefern. Laut der offiziellen Referenz ermöglicht JSON-Ausgabe mehrfeldige Antworten, die Claude zur Entscheidungsfindung interpretiert.
| { “allowed”: false, “message”: “This file is protected by team policy”, “suggestion”: “Create a new file in src/features/ instead” } |
Das Feld allowed steuert, ob die Operation fortgesetzt wird. Die Nachricht wird Claude als Kontext angezeigt. Das Feld suggestion bietet alternative Ansätze.
Damit Hooks JSON ausgeben können, müssen sie:
- Gültiges JSON an stdout schreiben
- Mit Code 0 (für erlaubt) oder 1 (für blockiert) beenden
- Mindestens das boolesche Feld allowed enthalten
Claude Code parst das JSON und nutzt es, um die Feedbackschleife zu verbessern. Exit-Codes bestimmen weiterhin die primäre Entscheidung, aber JSON bietet einen reichhaltigeren Kontext.
Referenz der Hook-Eingabefelder
Alle Hooks empfangen ein JSON-Objekt über stdin mit gemeinsamen Feldern und ereignisspezifischen Daten. Das Verständnis des vollständigen Schemas ermöglicht eine anspruchsvollere Hook-Logik.
Gemeinsame Eingabefelder
Jeder Hook empfängt diese Basis-Felder:
- event: Der Name des Hook-Ereignisses (z.B. "PreToolUse")
- sessionId: Eindeutiger Identifikator für die aktuelle Claude-Sitzung
- turnId: Identifikator für die aktuelle Konversationsrunde
- timestamp: ISO 8601 Zeitstempel, wann das Ereignis ausgelöst wurde
Tool-Ereignisfelder
PreToolUse-, PostToolUse- und PostToolUseFailure-Ereignisse enthalten:
- toolName: Name des aufgerufenen Tools (edit_file, execute_command usw.)
- toolInput: Objekt mit den Eingabeparametern des Tools
- toolResponse: Tool-Ausgabedaten (nur PostToolUse)
- error: Fehlerdetails, einschließlich Nachricht und Code (nur PostToolUseFailure)
Die Struktur von toolInput variiert je nach Tool. Für edit_file enthält sie path und content. Für execute_command enthält sie command und args.
Berechtigungsereignisfelder
PermissionRequest-Ereignisse enthalten:
- permissionType: Art der angeforderten Berechtigung (file_write, command_execute usw.)
- requestedAction: Spezifische Aktion, die eine Berechtigung erfordert
- resourcePath: Pfad der Datei oder Ressourcen-Identifikator, der betroffen ist
MCP Tool Hooks
Laut der offiziellen Hook-Referenz können Hooks mit dem mcpTool-Matcher-Feld auf Model Context Protocol (MCP) Tools abgleichen. Dies ermöglicht die Hook-Ausführung, wenn Claude externe Tools von MCP-Servern verwendet.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Der Wert mcpTool stimmt mit dem Toolnamen im Format server-name/tool-name überein. Dies ermöglicht Validierungslogik für Datenbankabfragen, API-Aufrufe oder andere externe Operationen.
GitHub-Feature-Anfragen zeigen ein wachsendes Interesse an einer tieferen MCP-Integration, einschließlich Hooks, die MCP-Server-Benachrichtigungen prüfen und auf externe Ereignisse reagieren können.
Sicherheitsüberlegungen
Hooks werden mit denselben Berechtigungen wie Claude Code selbst ausgeführt. Dies birgt Sicherheitsrisiken für Multi-User-Umgebungen und gemeinsam genutzte Konfigurationen.
Befehlsausführungs-Sandbox
Laut GitHub-Issue #28044 werden HTTP-Hooks über einen Sandbox-Proxy geleitet, der den Netzwerkzugriff einschränkt und Umgebungsvariablen filtert. Befehlshooks haben keine solchen Einschränkungen – sie laufen mit vollem Shell-Zugriff.
Die Dokumentation empfiehlt diese Praktiken:
- Speichern Sie niemals Anmeldeinformationen in Hook-Befehlen
- Verwenden Sie Umgebungsvariablen für sensible Daten
- Validieren Sie alle Eingaben aus ${…} Erweiterungen
- Implementieren Sie Timeout-Limits für externe Dienste
- Verwenden Sie asynchrone Hooks für nicht kritische Operationen, um Blockaden bei Fehlern zu vermeiden
Isolierung der Hook-Ausführung
Hooks auf Benutzerebene in ~/.claude/settings.json gelten für alle Projekte. Dies birgt Risiken, wenn Sie mit unterschiedlichen Vertrauensgrenzen arbeiten. Projekt-Hooks überschreiben Benutzer-Hooks, können sie aber nicht vollständig deaktivieren.
Das Menü /hooks in Claude Code zeigt alle aktiven Hooks für die aktuelle Sitzung an. Die Überprüfung dieser Liste vor der Arbeit an sensiblen Projekten hilft, potenzielle Sicherheitsprobleme zu identifizieren.
Debugging und Fehlerbehebung
Hook-Fehler werden nicht immer klar in Claude's Konversation angezeigt. Die offizielle Dokumentation bietet mehrere Debugging-Ansätze.
Hook-Ausführungsprotokolle
Claude Code protokolliert die Hook-Ausführung in der Sitzungs-Debug-Ausgabe. Laut der Fehlerbehebungsanleitung deckt die Aktivierung der Debug-Protokollierung auf:
- Welche Hooks für jedes Ereignis übereinstimmten
- Die an jeden Hook gesendete JSON-Eingabe
- Stdout- und stderr-Ausgabe von Hook-Prozessen
- Exit-Codes und Ausführungszeit
- HTTP-Statuscodes und Body für HTTP-Hooks
Aktivieren Sie die Debug-Protokollierung, indem Sie CLAUDE_DEBUG=1 in der Umgebung setzen, bevor Sie Claude Code starten.
Hooks unabhängig testen
Befehlshooks können außerhalb von Claude Code getestet werden, indem manuell JSON-Eingaben erstellt werden:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Dies validiert die Hook-Logik, ohne tatsächliche Claude-Operationen auszulösen. Der Exit-Code und die stdout/stderr-Ausgabe sollten dem erwarteten Verhalten entsprechen.
Häufige Hook-Fehler
Community-Diskussionen identifizieren diese häufigen Probleme:
- Timeout-Fehler: Der Standard-Timeout von 10 Minuten ist für langsame Operationen zu kurz – erhöhen Sie ihn mit dem Timeout-Feld
- Pfad-Erweiterungsfehler: Variablen wie ${file} sind für Ereignisse, die keinen Dateikontext enthalten, nicht definiert
- Berechtigungsfehler: Hook-Skripten fehlen Ausführungsberechtigungen – führen Sie chmod +x script.sh aus
- JSON-Parse-Fehler: Fehlerhaft formatierte JSON-Ausgabe von Hooks – validieren Sie mit jq, bevor Sie zurückkehren
- Umgebungsvariablen nicht verfügbar: Variablen werden nicht an den Hook-Prozess weitergeleitet – überprüfen Sie die Umgebung von Claude Code
Hook-Leistungsaspekte
Synchrone Hooks blockieren den Workflow von Claude bis zur Fertigstellung. Der Standard-Timeout von 10 Minuten verhindert unendliches Hängen, aber selbst kurze Verzögerungen summieren sich über mehrere Operationen.
Praktiker berichten, dass einfache Validierungs-Hooks kaum spürbare Auswirkungen auf die Leistung haben. Dateiformatierungs-Hooks haben spürbare, aber akzeptable Auswirkungen auf die Leistung. Externe API-Aufrufe können zu Reibungen im Workflow führen. Komplexe Berechnungsoperationen profitieren von asynchroner Ausführung.
Hook-Batching
Mehrere Hooks können mit demselben Ereignis übereinstimmen. Laut der Referenzdokumentation werden Hooks sequenziell in der Definitionsreihenfolge ausgeführt. Wenn ein Hook die Operation blockiert, werden die restlichen Hooks nicht ausgeführt.
Dies ist wichtig für die Leistung. Fünf synchrone Hooks zu je 200 ms summieren sich zu einer Sekunde pro Ereignis. Das Kombinieren verwandter Validierungen in einem einzigen Hook reduziert den Overhead.
Fortgeschrittene Muster
Über grundlegende Automatisierung hinaus ermöglichen Hooks eine anspruchsvolle Workflow-Anpassung.
Zustandsbehaftete Hook-Ketten
Hooks können den Zustand zwischen Ausführungen mithilfe von Dateien oder Datenbanken aufrechterhalten. Ein PostToolUse-Hook könnte erfolgreiche Operationen aufzeichnen, die ein PreToolUse-Hook später validiert:
| #!/bin/bash # Erfolgreiche Bearbeitungen aufzeichnen echo “${toolInput.path}” >> .claude/edit-history.txt |
Ein begleitender PreToolUse-Hook könnte diese Historie überprüfen, um redundante Operationen zu verhindern oder Reihenfolgebeschränkungen durchzusetzen.
Bedingte Hook-Aktivierung
Umgebungsvariablen steuern das Hook-Verhalten zur Laufzeit. Das Setzen von CLAUDE_SKIP_HOOKS=1 deaktiviert Hooks für Notfallsituationen.
Hooks selbst können Umgebungsflags prüfen:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Strikte Validierung anwenden exit 1 fi exit 0 |
Dies ermöglicht Verhaltensweisen im Entwicklungs- vs. Produktionsmodus ohne Konfigurationsänderungen.
Mehrstufige Validierung
PreToolUse-Hooks können mehrstufige Validierungen implementieren, bei denen Exit-Code 2 Claude erlaubt, mit Warnungen fortzufahren:
- Harte Fehler (Exit 1): Gefährliche Operationen blockieren
- Weiche Warnungen (Exit 2): Claude aufrufen, neu zu prüfen
- Erlauben mit Kontext (Exit 0 + JSON): Zusätzliche Informationen bereitstellen
Dies schafft ein Validierungsspektrum, das nuancierter ist als binäres Erlauben/Verweigern.
Integration mit CI/CD
Laut der offiziellen Dokumentation zur Plattformintegration läuft Claude Code in CI/CD-Umgebungen für automatisierte Code-Reviews und Triage von Problemen. Hooks erweitern diese Automatisierung.
GitHub Actions Workflows können Hooks definieren, die Teamrichtlinien während automatisierter Sitzungen erzwingen:
| -- name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Das Flag STRICT_MODE aktiviert bedingte Validierungslogik in Hook-Skripten. Dies stellt sicher, dass automatisierte Sitzungen strengeren Regeln folgen als die interaktive Entwicklung.
Audit-Trail-Generierung
PostToolUse-Hooks in CI-Umgebungen erstellen detaillierte Audit-Protokolle aller Claude-Operationen:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Hintergrundprotokollierung beeinträchtigt die Leistung nicht, bietet aber eine vollständige Betriebshistorie für Compliance und Debugging.
Das Menü /hooks
Claude Code bietet einen Befehl /hooks, der alle aktiven Hooks für die aktuelle Sitzung anzeigt. Laut der offiziellen Dokumentation zeigt dieses Menü:
- Hook-Ereignistyp
- Matcher-Muster
- Befehl oder URL-Endpunkt
- Ob der Hook asynchron ausgeführt wird
- Konfigurationsquelle (Projekt, Benutzer oder Plugin)
Durch Auswahl eines Hooks wird dessen vollständige Konfiguration angezeigt und die temporäre Deaktivierung für die aktuelle Sitzung ermöglicht.
Hooks deaktivieren oder entfernen
Hooks können deaktiviert werden, ohne die Konfiguration zu entfernen, indem "enabled": false zur Hook-Definition hinzugefügt wird. Dies bewahrt die Konfiguration, verhindert aber die Ausführung.
Um einen Hook dauerhaft zu entfernen, löschen Sie seinen Eintrag aus der entsprechenden settings.json-Datei. Änderungen werden beim nächsten Neustart der Sitzung wirksam oder wenn /reload ausgeführt wird.
Hooks in Skills und Agents
Laut der offiziellen Dokumentation gelten Hooks, die innerhalb von Skill- oder Subagent-Konfigurationen definiert sind, nur, wenn dieser Skill oder Agent ausgeführt wird. Dies ermöglicht spezialisierte Automatisierung für bestimmte Workflows.
Ein Debugging-Subagent kann Hooks enthalten, die alle Toolaufrufe protokollieren:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Diese Hooks werden nur während der Debugger-Agent-Sitzungen ausgelöst, nicht während des normalen Claude Code-Betriebs.
Skripte per Pfad referenzieren
Hook-Befehle unterstützen sowohl relative als auch absolute Pfade. Relative Pfade werden vom Projekt-Root aufgelöst, wo Claude Code ausgeführt wird.
Best Practices aus Community-Diskussionen:
- Speichern Sie Hook-Skripte im Verzeichnis .claude/hooks/
- Verwenden Sie aussagekräftige Namen: validate-typescript.sh statt hook1.sh
- Machen Sie Skripte ausführbar: chmod +x .claude/hooks/*.sh
- Fügen Sie eine Shebang-Zeile hinzu: #!/usr/bin/env bash oder #!/usr/bin/env python3
- Fügen Sie Fehlerbehandlung mit set -e in Bash-Skripten hinzu
Zukünftige Hook-Funktionen
GitHub-Feature-Anfragen zeigen geplante und angefragte Hook-Erweiterungen:
- Inline-Skript-Hooks: Definieren Sie Hook-Logik direkt in settings.json ohne externe Dateien
- MCP-Tool-Integration: Rufen Sie MCP-Server-Tools aus Hooks anstelle von Shell-Befehlen auf
- Multi-Agenten-Kollaboration: Hooks, die zwischen Claude-Instanzen auf verschiedenen Maschinen koordinieren
- Erweiterte Typisierungen: TypeScript-Typdefinitionen für Hook-Eingabe-/Ausgabeschemata
Laut GitHub-Issue #4274 zielt die Anfrage nach integrierten Hook-Typen (MCP-Tool, Inline-Skript, API-Aufruf) darauf ab, die Konfiguration zu vereinfachen und die Entwicklererfahrung zu verbessern.
Häufig gestellte Fragen
Können Hooks verhindern, dass Claude gefährliche Befehle ausführt?
Ja. PreToolUse-Hooks können jede Toolausführung blockieren, indem sie mit Code 1 beendet werden. Dazu gehören Dateibearbeitungen, Befehlsausführungen und MCP-Toolaufrufe. Der Hook erhält die vollständige Tool-Eingabe und kann Kriterien validieren, bevor die Operation zugelassen wird.
Wie debugge ich einen Hook, der nicht funktioniert?
Aktivieren Sie die Debug-Protokollierung mit CLAUDE_DEBUG=1, bevor Sie Claude Code starten. Überprüfen Sie die Sitzungsprotokolle auf Details zur Hook-Ausführung, einschließlich welcher Hooks übereinstimmten, die gesendete JSON-Eingabe, stdout/stderr-Ausgabe und Exit-Codes. Testen Sie Hooks unabhängig, indem Sie Beispiel-JSON an das Hook-Skript weiterleiten.
Funktionieren Hooks mit allen Claude Code-Plattformen?
Hooks funktionieren in der CLI, der Desktop-App und der VS Code-Erweiterung. Laut der offiziellen Dokumentation werden Hooks überall dort ausgeführt, wo Claude Code mit Zugriff auf das Dateisystem ausgeführt wird. Browserbasierte Claude- und mobile Apps unterstützen Hooks aufgrund von Sandboxing-Beschränkungen nicht.
Können Hooks Claude's Antworten oder Verhalten modifizieren?
Prompt-Hooks injizieren Anweisungen, die das Verhalten von Claude beeinflussen. Agent-Hooks delegieren die Ereignisverarbeitung an spezialisierte Subagenten. Hooks können jedoch nicht direkt Claude's generierten Text oder seinen Denkprozess ändern – sie funktionieren, indem sie Kontext bereitstellen und Operationen blockieren.
Was ist der Unterschied zwischen asynchronen und synchronen Hooks?
Synchrone Hooks blockieren den Workflow von Claude bis zur Fertigstellung oder zum Timeout. Asynchrone Hooks laufen im Hintergrund, ohne zu blockieren. Sync-Hooks können Operationen durch Exit-Codes verhindern. Async-Hooks können nicht blockieren, da Claude fortfährt, bevor der Hook abgeschlossen ist. Verwenden Sie async für Protokollierung und Benachrichtigungen, sync für Validierung.
Wie teile ich Hooks teamübergreifend?
Übergeben Sie die Datei .claude/settings.json an die Versionskontrolle. Projekt-Hooks gelten für alle Teammitglieder, die das Repository klonen. Für unternehmensweite Richtlinien können Teams eine gemeinsam genutzte Benutzerebene-Einstellungsdatei pflegen, die die Mitglieder in ~/.claude/settings.json kopieren.
Können HTTP-Hooks interne APIs hinter Firewalls aufrufen?
Ja, wenn Claude Code in einer Umgebung mit Netzwerkzugriff auf diese APIs ausgeführt wird. HTTP-Hooks senden Standard-POST-Anfragen von der Maschine, auf der Claude Code ausgeführt wird. Unternehmensfirewalls und VPNs gelten normal. Der in der Dokumentation erwähnte Sandbox-Proxy steuert die Offenlegung von Umgebungsvariablen, nicht das Netzwerk-Routing.
Erhöhen Hooks die Token-Nutzung von Claude Code?
Prompt-Hooks injizieren Text in Claude's Kontext, was Token verbraucht. Befehls- und HTTP-Hooks wirken sich nicht direkt auf die Token-Nutzung aus, aber ihre Ausgabe (Fehlermeldungen, Vorschläge) wird Teil des Konversationskontexts. Exit-Code 2 mit erklärenden Meldungen fügt mehr Kontext hinzu als Exit-Code 1 mit einfacher Blockierung.
Schlussfolgerung
Claude Code Hooks verwandeln den KI-Assistenten von einem leistungsstarken Werkzeug in eine vollautomatisierte Entwicklungsplattform. Das Ereignissystem bietet Abfangpunkte während des gesamten Workflows von Claude – von der Sitzungsinitialisierung bis zur Kontextverdichtung.
Befehlshooks behandeln lokale Validierung und Formatierung. HTTP-Hooks integrieren externe Dienste und Datenbanken. Prompt-Hooks ändern das Verhalten durch Kontextinjektion. Gemeinsam ermöglichen diese Automatisierungsmuster, die Teamrichtlinien durchsetzen, die Codequalität aufrechterhalten und sich in die bestehende Entwicklungsinfrastruktur integrieren.
Das Matcher-System filtert Hooks auf bestimmte Tools und Dateimuster. Exit-Codes und JSON-Ausgabe steuern den Entscheidungsfluss. Asynchrone Ausführung verhindert Blockaden bei langsamen Operationen. Das vollständige Konfigurationsschema unterstützt alles von einfacher automatischer Formatierung bis hin zu komplexer mehrstufiger Validierung.
Beginnen Sie mit einfachen PostToolUse-Hooks für die Codeformatierung. Fügen Sie PreToolUse-Validierung hinzu, wenn Richtlinien entstehen. Experimentieren Sie mit Prompt-Hooks zur Verhaltensänderung. Erstellen Sie HTTP-Integrationen für die teamweite Durchsetzung.
Schauen Sie in der offiziellen Claude Code-Dokumentation nach der vollständigen Hook-Referenz und dem aktualisierten Konfigurationsschema, wenn neue Funktionen veröffentlicht werden.
