Claude Code Hooks: settings.json, die 5 Events & Exit-Code-Blocking
Hooks sind die deterministische Schicht von Claude Code: Sie laufen immer, ganz ohne Prompting. Dieser bebilderte Walkthrough nutzt Anthropics eigenes Hooks-Video für die Bilder – die fünf Events, ein PreToolUse-Block-Script, strukturiertes Deny-JSON und eine komplette PostToolUse-Formatting-Konfiguration.
TL;DR – was Claude-Code-Hooks sind
- Hooks sind deterministisch: Sie laufen an festen Punkten im Lebenszyklus von Claude Code, jedes einzelne Mal. Eine CLAUDE.md-Anweisung wie „nach jeder Bearbeitung Prettier ausführen“ funktioniert meistens – ein Hook funktioniert immer.
- Es gibt fünf Events: UserPromptSubmit (bevor dein Prompt verarbeitet wird), PreToolUse (vor einem Tool-Aufruf), PostToolUse (nach Abschluss eines Tools), Notification und Stop (wenn Claude mit der Antwort fertig ist).
- Ein PreToolUse-Hook, der mit Exit Code 2 endet, blockiert den Tool-Aufruf, und die stderr-Meldung geht zurück an Claude, damit es weiß, warum. Exit Code 0 lässt den Aufruf durch.
- Hooks leben in settings.json – ein Event, ein optionaler Tool-Matcher und ein Befehl. Leg sie in die .claude/settings.json des Projekts und committe sie, dann erbt dein ganzes Team dieselben Garantien.
Hooks in Claude Code
Kanal:Claude (official Anthropic channel)3:22
Claude Code Hooks, Explained Simply
Kanal:Agentic Lab8:32
Claude Code - Getting Started with Hooks
Kanal:Greg Baugues11:53
Hooks reference — Claude Code documentation
Doku:code.claude.com
Die Frames in diesem Guide stammen aus Anthropics offiziellem Hooks-Erklärvideo; der Walkthrough-Text wurde unabhängig geschrieben und mit der offiziellen Hooks-Referenz abgeglichen.
Screenshots bleiben Eigentum ihrer Ersteller und werden mit Quellenangabe als visuelle Dokumentation verwendet. Jeder Schritt verlinkt zurück auf die exakte Stelle im Quellvideo.
Claude-Code-Hooks einrichten, Schritt für Schritt
1 · Wie Hooks in freier Wildbahn aussehen
- 1
Zusehen, wie ein Hook am Ende einer Antwort feuert
Die Statuszeile zeigt „Running stop hook · 39s · 484 tokens“ – Claude Code führt einen Stop-Hook aus, bevor es den Turn an dich zurückgibt. Das ist die ganze Idee in einem Screenshot: Ein von dir registrierter Befehl läuft an einem festen Punkt im Lebenszyklus, bei jedem passenden Ereignis, ganz ohne das Vertrauen darauf, dass sich das Modell etwas merkt.
Ein Stop-Hook läuft nach Claudes Antwort – 39 Sekunden vergangen, 484 Tokens verbraucht.Ab 0:10 ansehen - 2
Die fünf Hook-Events kennenlernen
UserPromptSubmit feuert, sobald du einen Prompt abschickst, bevor Claude ihn verarbeitet. PreToolUse läuft vor jedem Tool-Aufruf. PostToolUse läuft nach Abschluss eines Tool-Aufrufs. Notification feuert, wenn Claude eine Benachrichtigung sendet, und Stop läuft, wenn Claude mit der Antwort fertig ist. Jeder Hook, den du schreibst, hängt an genau einem dieser fünf Punkte.
Die fünf Events aus Anthropics offiziellem Hooks-Video – alles andere hängt an dieser Liste.Ab 1:04 ansehen
2 · Deine ersten Hooks schreiben
- 3
Einen hooks-Block in settings.json ergänzen
Ein Hook ist in settings.json ein Dreiklang: der Event-Name, ein optionaler Matcher, der eingrenzt, auf welches Tool er sich bezieht, und der auszuführende Befehl. Im Screenshot wird der PreToolUse-Matcher gerade mit Edit vervollständigt – dieser Hook feuert nur bei Datei-Bearbeitungen. Wer kein JSON anfassen will, editiert dieselbe Konfiguration interaktiv im /hooks-Menü.
Der Matcher vervollständigt sich zu Edit und schränkt den PreToolUse-Hook auf Datei-Edits ein.Ab 0:14 ansehen - 4
Gefährliche Befehle mit Exit Code 2 blockieren
Ein PreToolUse-Hook erhält Toolname und Eingabe als JSON auf stdin. Dieses Script leitet es durch jq, um .tool_input.command zu greifen, sucht mit grep nach destruktiven Mustern – rm -rf, git push --force – und gibt bei einem Treffer den Grund auf stderr aus und beendet sich mit 2. Exit Code 2 blockiert den Aufruf; der stderr-Text geht als Feedback an Claude zurück, damit das Modell weiß, warum es blockiert wurde, und sich anpassen kann.
jq liest den Befehl von stdin; ein Treffer auf rm -rf oder --force schreibt auf stderr und beendet mit 2.Ab 2:02 ansehen - 5
Eine strukturierte Ablehnung statt eines Exit Codes senden
Für feinere Kontrolle kann ein Hook eine JSON-Entscheidung ausgeben, statt auf Exit Codes zu setzen. Hier fängt ein PreToolUse-Hook DROP TABLE ab, und hookSpecificOutput trägt permissionDecision „deny“ plus einen Grund – „nutze stattdessen eine Migration“ – der direkt in den Kontext des Modells landet. Dieselbe harte Garantie, aber mit einer umsetzbaren Anweisung angehängt.
Ein permissionDecision von deny blockiert den SQL-Befehl und sagt dem Modell, was stattdessen zu tun ist.Ab 2:16 ansehen - 6
Hooks im Repo halten, damit das Team sie bekommt
Hooks, die in der .claude/settings.json des Projekts konfiguriert sind, sind auf Projektebene und lassen sich committen. Jeder, der das Repo klont, läuft automatisch mit denselben Hooks – auch den blockierenden. Lege Hilfsscripts in .claude/hooks/ ab und referenziere sie über die Umgebungsvariable CLAUDE_PROJECT_DIR, damit die Pfade sich auflösen, egal wo Claudes aktuelles Arbeitsverzeichnis liegt.
Der .claude-Ordner des Projekts enthält settings.json plus einen hooks/-Ordner mit geteilten Scripts.Ab 0:17 ansehen - 7
Eine komplette, echte Hooks-Konfiguration kopieren
Diese Konfiguration erledigt zwei Jobs gleichzeitig. Der PostToolUse-Block matcht Edit|Write|MultiEdit und führt .claude/hooks/auto-format.sh mit 30 Sekunden Timeout aus – jede Datei, die Claude anfasst, wird formatiert. Darunter matcht ein zweiter Hook Bash und loggt jeden ausgeführten Befehl – das Compliance-Muster. Die Felder timeout und async verhindern, dass langsame Formatter die Sitzung blockieren.
PostToolUse-Autoformatierung mit 30s Timeout, dazu ein Bash-Hook, der jeden Befehl loggt.Ab 2:46 ansehen
3 · Sie wie ein Team betreiben
- 8
Den Exit-Code-Vertrag auswendig können
Exit Code 0 heißt: weitermachen. Exit Code 2 heißt: blockieren – und stderr geht als Feedback an Claude, das damit arbeiten kann. Jeder andere Exit Code zeigt dir als Nutzer stderr, aber der Tool-Aufruf läuft weiter; nutz das für Warnungen, die du sehen willst, ohne den Agenten hart zu blockieren.
- 9
Hooks über das /hooks-Menü registrieren und Rezepte wählen
Der Befehl /hooks öffnet dieselbe Konfiguration interaktiv – praktisch, um zu prüfen, welche Hooks in welchem Scope registriert sind. Von hier zu den vier Arbeitstier-Rezepten: nach Edits automatisch formatieren (PostToolUse), alle ausgeführten Befehle loggen (PostToolUse auf Bash), gefährliche Operationen blockieren (PreToolUse mit Exit 2) und sich benachrichtigen lassen, wenn Claude fertig ist (Stop). Wenn etwas jedes Mal ohne Ausnahme passieren muss, gehört es nicht in einen Prompt – sondern in einen Hook.
Der Exit-Code-Vertrag in einer Tabelle
Jeder Hook-Befehl kommuniziert über seinen Exit Code. Drei Fälle decken alles ab, was du brauchst:
- exit 0Weitermachen. Der Tool-Aufruf läuft normal. stdout vom Hook ist im Transcript-Modus sichtbar (Ctrl-R).
- exit 2Blockieren. Der Tool-Aufruf wird abgelehnt und die stderr-Ausgabe des Hooks geht als Feedback an Claude zurück, sodass das Modell korrigieren kann – das macht Exit-2-Hooks lehrreich statt nur fatal.
- exit 1Jeder andere Code: warnen statt blockieren. stderr wird dir gezeigt, aber der Aufruf läuft weiter. Nutze das für Hinweis-Hooks – „diese Datei ist normalerweise generiert, bist du sicher?“
Ein weiterer Upgrade-Weg: Statt Exit Codes kann ein Hook eine JSON-Entscheidung ausgeben (hookSpecificOutput mit permissionDecision), um mit strukturiertem Grund zu blockieren, wie in Schritt 5. Exit Codes sind der einfache Vertrag; JSON-Entscheidungen sind der typisierte.
Vier Rezepte, die sich heute zu committen lohnen
Das offizielle Video nennt vier Use Cases; hier sind sie als Copy-Paste-Absicht:
- 1Nach Edits automatisch formatieren – ein PostToolUse-Hook matcht Edit|MultiEdit, prüft die Dateiendung und ruft den richtigen Formatter auf: Prettier für TypeScript, gofmt für Go, Ruff für Python.
- 2Jeden ausgeführten Befehl loggen – ein PostToolUse-Hook auf Bash hängt jeden Befehl an eine Datei an. Compliance-Teams lieben das; dein zukünftiges Ich beim Debuggen vom letzten Dienstag auch.
- 3Gefährliche Operationen blockieren – ein PreToolUse-Hook mit Exit 2 bewacht Produktiv-Konfigverzeichnisse, rm -rf-Muster oder Commits auf main. Daraus werden Garantien, keine Vorschläge.
- 4Benachrichtigen, wenn die Aufgabe fertig ist – ein Stop- oder Notification-Hook löst eine Desktop-Benachrichtigung oder einen Sound aus, damit lange Agent-Läufe kein Babysitting brauchen.
Alle vier passen in eine .claude/settings.json. Fang mit dem Formatter an – das ist der Hook, den du bei jedem einzelnen Speichern spürst.