Drei Monate. So lange ließ ich Claude Code Hooks in der Dokumentation ungelesen, während ich mich beschwerte, dass die KI immer wieder Code produzierte, der meine Formatierungskonventionen ignorierte. Ich hatte Claude Code im Januar eingerichtet, begann fast sofort, Features damit auszuliefern, und sagte mir selbst, ich würde mich „später um das Hooks-Ding kümmern". Klassisch.
Es stellte sich heraus, dass die Hooks keine Nice-to-Have waren. Sie waren das fehlende Stück, das Claude Code tatsächlich in einen echten Agency-Workflow integrierte, anstatt nur ein sehr teures Autocomplete zu sein, das gelegentlich ESLint ignorierte.
Was Claude Code Hooks wirklich sind (Keine vagen Abstraktionen)
Hooks sind Shell-Befehle, die Claude Code an bestimmten Punkten während seines eigenen Betriebs ausführt. Denk sie dir wie Lifecycle-Events ähnlich Git-Hooks, falls du je ein Pre-Commit-Skript geschrieben hast, aber in die KI-Tool-Use-Schleife verdrahtet statt in Gits Commit-Pipeline.
Es gibt derzeit vier Event-Typen:
PreToolUse, läuft, bevor Claude ein Tool aufruft (Dateibearbeitungen, Bash-Befehle usw.)PostToolUse, läuft nach Abschluss eines Tool-AufrufsNotification, wird ausgelöst, wenn Claude dir eine Benachrichtigung sendetStop, läuft, wenn Claude seinen vollständigen Response-Turn beendet
Du konfigurierst sie in einer settings.json Datei im .claude/ Ordner deines Projekts oder global in ~/.claude/settings.json wenn du sie überall haben möchtest. Jeder Hook erhält einen matcher (welches Tool oder Event ihn triggert) und ein hooks Array von Shell-Befehlen, die ausgeführt werden sollen.
Die Ausgabe deines Hooks wird in Claudes Kontext zurückgespeist. Genau das macht das wirklich interessant, anstatt nur ein ausgefallener Cron-Job zu sein.
Warum das anders ist als selbst Scripts auszuführen
Du könntest Prettier nach jeder Claude-Bearbeitung manuell ausführen. Ich tat es etwa zwei Wochen lang, bis ich während eines Deadline-Drucks vergaß und einen PR mit 47 Formatierungsverletzungen hochlud. Die Hooks laufen automatisch, innerhalb der Sitzung, und Claude kann ihre Ausgabe lesen. Wenn also dein Linter eine Warnung wirft, sieht Claude sie und kann in derselben Sitzung darauf reagieren. Diese Feedback-Schleife ist der ganze Sinn dahinter.
Das Setup, das tatsächlich für Seahawk-Projekte funktionierte
Ich werde hier spezifisch, weil der generische Rat „füge Hooks zu deiner Config hinzu", den du in den meisten Beiträgen findest, ohne Kontext nutzlos ist.
Bei Seahawk ist ein großer Teil unserer Arbeit WordPress-Builds und WooCommerce-Anpassungen. Wir machen auch React-Frontends für Headless-Setups, und wir verwenden Next.js seit 2022 intensiv. Die Hook-Konfiguration, bei der ich landete, behebt Probleme, die spezifisch für diese Stacks sind.
Hier ist die settings.json Struktur, die ich für ein Next.js-Projekt nutze:
`` { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATHS && npx eslint --fix $CLAUDE_FILE_PATHS" } ] } ], "Stop": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -20" } ] } ] } } ``
Der PostToolUse Hook feuert Prettier und ESLint sofort ab, nachdem Claude eine Datei anfasst. Der Stop Hook führt eine TypeScript-Typprüfung am Ende jedes Turns aus und zeigt die ersten 20 Zeilen aller Fehler an. Claude liest diese Ausgabe, und wenn es Typfehler gibt, behebt er sie, bevor ich die Antwort überhaupt sehe.
Allein diese TypeScript-Prüfung hat mir wahrscheinlich vier Stunden letzten Monat bei einem Fintech-Dashboard-Projekt gespart, bei dem der Client noImplicitAny streng gesetzt hatte. Claude generierte ständig any-Typen in Utility-Funktionen. Nachdem ich den Stop-Hook hinzugefügt habe, begann er, sich selbst innerhalb desselben Durchlaufs zu korrigieren.
Die Hooks, die ich bei WordPress-/PHP-Projekten verwende
WordPress ist ein anderes Tier. Kein TypeScript, natürlich, aber PHP_CodeSniffer mit dem WordPress Coding Standards Regelwerk hält die Dinge in Ordnung. 2022 hatte ich einen Junior Developer auf einem WooCommerce-Projekt, der zwei Wochen lang PHPCS nicht ausgeführt hatte. Die Code Review war... nicht angenehm.
Bei PHP-intensiven Projekten führt mein PostToolUse-Hook aus:
`` vendor/bin/phpcs --standard=WordPress $CLAUDE_FILE_PATHS 2>&1 | tail -30 ``
Und ich kombiniere das mit einem PreToolUse-Hook auf Bash-Befehle:
`` { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash tool triggered' >> ~/.claude/audit.log && date >> ~/.claude/audit.log" } ] } ``
Das zweite ist reine Paranoia. Es schreibt jeden Bash-Befehl, den Claude ausführt, in ein Audit-Log. Wenn du Claude Code auf einer Live-Staging-Umgebung laufen lässt (ja, ich habe es getan, ja, es ist etwas riskant), ist es genuinely beruhigend zu wissen, welche Shell-Befehle genau ausgeführt wurden.
Verhalten mit Hook-Exit-Codes blockieren
Diese Part der Dokumentation hat mich lange gekostet zu finden. Wenn dein Hook mit Code 2 beendet wird, behandelt Claude Code das als Blockade und führt den Tool-Aufruf nicht aus. Exit-Code 0 ist Erfolg, alles nicht-null (aber nicht 2) gibt stderr als Kontext zurück.
Du kannst also einen PreToolUse-Hook schreiben, der Claude tatsächlich davon abhält, etwas zu tun. Ich verwende das bei Projekten, die ein migrations/-Verzeichnis haben, das Claude nicht autonom anfassen soll:
`` #!/bin/bash if echo "$CLAUDE_FILE_PATHS" | grep -q "migrations/"; then echo "Migrations folder is protected. Do not edit migration files autonomously." exit 2 fi exit 0 ``
Dieses Skript befindet sich unter .claude/hooks/guard-migrations.sh. Wenn Claude versucht, in etwas unter migrations/ zu schreiben, wird es blockiert und sieht die Nachricht. Es fragt mich dann, um Bestätigung zu bitten, bevor es fortfährt. Einfach, effektiv.
Das ist die Art von Kontrolle, die den Unterschied macht zwischen „ich vertraue dieser KI irgendwie mit meiner Codebasis" und „ich vertraue ihr wirklich mit meiner Codebasis".
Praktische Hook-Muster, die es wert sind, geklaut zu werden
Das sind keine theoretischen. Jedes kam aus einem spezifischen Pain Point.
- Auto-Tests nach Dateibearbeitungen. Ich führe
npx jest --testPathPattern=$CLAUDE_FILE_PATHS --passWithNoTestsin einemPostToolUse-Hook aus. Es führt nur Tests aus, die mit der Datei verknüpft sind, die Claude gerade bearbeitet hat, nicht die ganze Suite. Schnell genug, um nicht lästig zu sein. - Commit-ready Formatierungs-Snapshot. Ein Stop-Hook, der
git diff --statausführt und die Zusammenfassung an Claude zurückgibt. Es sieht genau, was sich während der Sitzung geändert hat, was ihm hilft, eine sinnvolle Commit-Nachricht zu schreiben, wenn ich danach frage. - Umgebungsvariablen-Sicherheitsprüfung. Ein PreToolUse-Hook auf Write, der nach hartcodierten Geheimnis-Mustern sucht (Dinge, die wie API-Schlüssel oder Passwörter aussehen). Wenn es etwas Verdächtiges findet, exit
2. Ich hätte das vor etwa 18 Monaten bauen sollen. - Benachrichtigungs-Hook für lange Aufgaben. Wenn Claude eine Benachrichtigung sendet (das Notification-Event), feuere ich einen
curl-Aufruf an einen Pushover-Endpoint, damit ich eine Push-Benachrichtigung auf meinem Telefon bekomme. Echt nützlich, wenn du eine große Refaktorierung startest und dir einen Tee machst. - PHP-Syntax-Prüfung vor Bash. Bei WordPress-Projekten eine schnelle
php -l $CLAUDE_FILE_PATHSvor jeder Bash-Ausführung. Fängt fatale Syntax-Fehler ab, bevor sie einen Staging-Server zerstören.
Die offizielle Claude Code Hooks-Dokumentation hat eine vollständige Referenz für Umgebungsvariablen, die in Hook-Skripten verfügbar sind. Wert zu speichern.
Was Hooks nicht beheben
Ehrlichkeit zählt hier. Hooks sind keine Lösung für Claude, der logisch falschen Code generiert. Sie beheben Prozessprobleme: Formatierung, Linting, Typ-Sicherheit, Test-Abdeckung. Wenn Claude dein Datenmodell falsch versteht und die falsche Funktion baut, wird kein Post-Edit-Linting das fangen.
Hooks fügen auch Latenz hinzu. Wenn dein Prettier + ESLint Pass vier Sekunden dauert, dauert jede Dateibearbeitung jetzt vier Sekunden länger. Bei einem Projekt mit 200 Dateibearbeitungen in einer Sitzung sind das 13 Minuten Wartezeit. Profiliere deine Hook-Befehle. Halte sie schnell. Ich führe --fix-Varianten aus (die Dateien direkt verändern), anstatt nur-Report-Varianten, genau weil ein einzelner schneller Durchlauf einen langsamen Durchlauf gefolgt von einem zweiten korrigierenden Durchlauf schlägt.
Und sie erfordern, dass du tatsächlich über die Fehlermodi deines Projekts vorausdenken musst. Was kann schiefgehen, wenn Claude die falsche Datei bearbeitet? Welche Standards müssen unbedingt durchgesetzt werden? Dieses Denken ist wertvoll, unabhängig, aber es bedeutet, dass Hooks erfahrene Entwickler mehr belohnen als Anfänger.
Hooks einrichten: Schritt für Schritt
Für alle, die bei null anfangen:
- Erstellen Sie einen
.claude/-Ordner in Ihrem Projekt-Root, falls er nicht existiert. - Fügen Sie eine
settings.json-Datei mit Ihrer Hooks-Konfiguration hinzu (Struktur siehe oben). - Bei mehr als einer einzeiligen Anweisung schreiben Sie ein separates Shell-Skript (.claude/hooks/your-script.sh), machen Sie es mit
chmod +xausführbar und rufen Sie es aus der Konfiguration auf, statt den Befehl inline zu schreiben. - Testen Sie, indem Sie
Claudein Ihrem Projekt ausführen und die Hook-Bedingung absichtlich auslösen. Lesen Sie, was in der Session-Kontextumgebung zurückkommt. - Überprüfen Sie die Hook-Ausführungsprotokolle unter
~/.claude/logs/, falls etwas nicht wie erwartet ausgelöst wird.
Die Anthropic-Entwicklerdokumentation behandelt das vollständige Einstellungsschema. Und wenn Sie überlegen, wie Hooks in breitere KI-Programmierungsworkflows passen, würde ich jeden, der sorgfältiger über agentenbasierte KI-Tooling in echten Projekten nachdenken möchte, zu Simon Willisons Blog schicken.
Eines habe ich anfangs falsch verstanden: Ich habe alle meine Hooks in der globalen ~/.claude/settings.json platziert und mich dann gewundert, warum meine PHP-Hooks in JavaScript-Projekten ausgelöst wurden. Projektebenen-Einstellungen setzen globale außer Kraft. Legen Sie Stack-spezifische Hooks in die .claude/settings.json des Projekts und reservieren Sie Ihre globale Konfiguration für Dinge, die überall gelten sollten (wie das Audit-Log und der Benachrichtigungshook).
FAQ
Funktionieren Claude Code Hooks unter Windows?
Die Hook-Befehle werden in der Shell ausgeführt, die Ihr System verwendet. Unter Windows ist das standardmäßig PowerShell oder CMD, was bedeutet, dass bash-artige Skripte nativ nicht funktionieren. WSL2 ist die praktische Antwort hier. Ich nutze macOS und Ubuntu auf meinen Dev-Boxen, bin also persönlich nicht darauf gestoßen, aber die Anthropic-Docs vermerken die Shell-Abhängigkeit explizit.
Können Hooks auf Claudes Gesprächskontext zugreifen?
Nicht direkt. Hooks werden als Shell-Befehle ausgeführt und erhalten Umgebungsvariablen wie CLAUDE_FILE_PATHS und CLAUDE_TOOL_NAME, aber sie erhalten die vollständige Gesprächsaufzeichnung nicht. Was sie können, ist Ausgaben auf stdout schreiben, die Claude als Kontext nach der Hook-Ausführung liest.
Verlangsamen Hooks meine Claude Code Sessions merklich?
Hängt ganz davon ab, was Ihre Hooks tun. Eine php -l Syntaxprüfung auf einer einzelnen Datei liegt unter 100ms. Ihre komplette Jest-Suite bei jedem Datei-Edit auszuführen wäre mächtig nervend. Halten Sie einzelne Hook-Befehle unter zwei bis drei Sekunden und Sie werden sie kaum bemerken.
Sind Hooks sicher zur Verwendung in Produktionsumgebungen?
Ich würde diese Frage anders herum stellen: Führen Sie Claude Code direkt in der Produktion aus? Falls ja, sind Hooks das geringste Ihrer Sorgen. Nutzen Sie sie auf Staging, verwenden Sie das PreToolUse-Blocking-Muster, um sensible Verzeichnisse zu schützen, und halten Sie Claude vollständig von Produktionsdatenbanken fern.
Was ist der Unterschied zwischen projektebenen- und globalen Hooks?
Globale Hooks befinden sich in ~/.claude/settings.json und gelten für jede Claude Code Session auf Ihrem Rechner. Projektebenen-Hooks befinden sich in .claude/settings.json innerhalb eines spezifischen Projekts und werden nur ausgelöst, wenn Sie sich in diesem Projekt befinden. Projektebene hat Vorrang, wenn beide dasselbe Event definieren.
---
Die ehrliche Zusammenfassung: Hooks sind nicht glamourös. Niemand wird einen Blog-Post über die schöne Architektur eines Shell-Skripts schreiben, das Prettier ausführt. Aber sie sind der Unterschied zwischen Claude Code als prototypisches Spielzeug und etwas, dem Sie wirklich auf Client-Arbeiten vertrauen würden. Ich hätte sie am ersten Tag einrichten sollen. Sie sollten das wahrscheinlich auch.