Claude Code Hooks sind Shell-Befehle, die Claude Code automatisch an bestimmten Punkten in seinem Lebenszyklus ausführt, damit du deine Quality Gates deterministisch durchsetzt, statt zu hoffen, dass der Agent sich daran erinnert. Wo eine CLAUDE.md-Regel ein Vorschlag ist, dem das Modell folgen kann oder nicht, feuert ein Hook immer: Er kann deinen Formatter nach jedem Datei-Schreibvorgang ausführen, deine Tests laufen lassen, bevor der Agent stoppt, oder einen gefährlichen Befehl direkt blockieren. Dieser Guide erklärt die Hook-Events, wie Hooks konfiguriert werden, und ein praktisches Setup, das du heute übernehmen kannst.
Teil von: Claude Code Tutorial fuer Einsteiger
Was ein Hook tatsächlich ist
Jeder Hook hat drei Teile: ein Event (der Lifecycle-Moment, in dem er feuert), einen optionalen Matcher (ein Filter, damit er nur für bestimmte Tools läuft) und eine Action (der Shell-Befehl, den er ausführt). Wenn ein Hook feuert, übergibt Claude Code ihm JSON über die Standardeingabe, das das Event beschreibt (Session-ID, Arbeitsverzeichnis, den Tool-Namen und seinen Input), und dein Skript entscheidet, was zu tun ist. Der Exit-Code des Befehls steuert den Ablauf: Exit 0 heisst weitermachen, und ein Exit ungleich null (konventionell 2) blockiert die Aktion und gibt deine Nachricht an den Agenten zurück, damit er reagieren kann.
- Event: wann der Hook feuert (zum Beispiel nachdem ein Tool gelaufen ist).
- Matcher: ein optionaler Filter, zum Beispiel nur bei Datei-Edits.
- Action: der Shell-Befehl, den Claude Code ausführt.
Die Lifecycle-Events, die du hooken kannst
Hooks decken den vollen Tool-Lebenszyklus ab. Die, die du am meisten nutzt, sind PreToolUse und PostToolUse (rund um jeden Tool-Aufruf), Stop (wenn der Agent fertig werden will) und SessionStart (wenn eine Session beginnt). Für feinere Kontrolle gibt es weitere.
- PreToolUse: bevor ein Tool läuft - die Aktion validieren oder blockieren.
- PostToolUse: nachdem ein Tool gelaufen ist - formatieren, linten oder das Ergebnis prüfen.
- UserPromptSubmit: wenn du einen Prompt schickst - Kontext einfügen oder Input absichern.
- Stop und SubagentStop: wenn der Agent (oder ein Subagent) stoppen will - Tests als letztes Gate laufen lassen.
- SessionStart und Notification: Session-Setup und wenn der Agent deine Aufmerksamkeit braucht.
Wo Hooks konfiguriert werden
Hooks leben in deiner Claude Code settings.json. Leg teamweite, nicht verhandelbare Gates in die Projektdatei unter .claude/settings.json, damit alle dieselben Leitplanken teilen, und behalte persönliche Vorlieben in deinen User-Settings. Jeder Eintrag paart ein Event mit einem Matcher und dem Befehl, der laufen soll.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "bun run lint --fix" }
]
}
]
}
}Ein praktisches Quality-Gate-Setup
Das wirkungsvollste Setup ist klein: bei jedem Write formatieren und linten, und deine Testsuite als Stop-Gate laufen lassen, damit der Agent eine Aufgabe nicht mit roten Tests für erledigt erklären kann. Füge einen PreToolUse-Guard hinzu, wenn du destruktive Shell-Befehle blockieren willst. Halte Hook-Skripte schnell und idempotent, weil sie oft laufen, und schreib bei einem Block eine klare Nachricht auf die Standardfehlerausgabe, damit der Agent weiss, wie er es behebt.
Schritt für Schritt
Erstelle deine Settings-Datei
Erstelle .claude/settings.json im Wurzelverzeichnis deines Projekts, falls sie nicht existiert. Hier leben gemeinsame, teamweite Hooks.
Füge einen PostToolUse-Hook fürs Formatieren und Linten hinzu
Füge unter hooks.PostToolUse einen Matcher "Edit|Write" und einen Befehl hinzu, der deinen Formatter und Linter ausführt, damit Code nach jeder Änderung des Agenten aufgeräumt wird.
Füge einen Stop-Hook hinzu, der deine Tests ausführt
Füge unter hooks.Stop einen Befehl hinzu, der deine Testsuite ausführt. Exit ungleich null bei Fehlschlag, damit der Agent nicht mit fehlschlagenden Tests fertig werden kann und sie stattdessen weiter behebt.
Füge einen PreToolUse-Guard für riskante Befehle hinzu
Füge unter hooks.PreToolUse mit einem Bash-Matcher ein Skript hinzu, das den Befehl aus dem stdin-JSON prüft und mit Exit 2 destruktive Operationen wie Force-Push oder rekursives Löschen blockiert.
Testen und committen
Mach einen kleinen Edit und bestätige, dass die Hooks wie erwartet feuern, dann committe die Settings-Datei, damit das ganze Team dieselben Leitplanken erbt.