Claude Code Hooks: Anleitung mit fünf Beispielen
So richtest Du Hooks in Claude Code ein: settings.json, PreToolUse und PostToolUse, Exit-Codes und fünf Beispiele von Prettier bis zur .env-Sperre.
Von Nathan Base
Du kannst in die CLAUDE.md schreiben, dass Claude Code nach jeder Änderung den Formatter laufen lassen und die .env nicht anfassen soll. Meistens hält es sich daran, aber eben nur meistens. Hooks schließen diese Lücke: Das sind Shell-Befehle, die Claude Code selbst an festen Punkten ausführt, etwa vor oder nach jedem Tool-Aufruf, ganz gleich, was das Modell gerade entscheidet.
Hier erfährst Du, welche Ereignisse es gibt, wo Hooks konfiguriert werden und wie Claude Code die Rückmeldung Deines Skripts auswertet. Dazu kommen fünf Beispiele zum Übernehmen: Prettier nach jeder Änderung, eine Sperre für sensible Dateien, eine Desktop-Benachrichtigung, ein Testlauf vor dem Abschluss und ein Protokoll aller Bash-Befehle. Grundlage sind die offizielle Anleitung Automate actions with hooks und die Hooks reference, Stand November 2026 mit Claude Code 2.1. Läuft Claude Code bei Dir noch nicht, hilft Dir zuerst die Anleitung: Claude Code auf dem Mac installieren & nutzen.
Was Hooks sind und wann sie feuern
Ein Hook hängt an einem Ereignis im Ablauf von Claude Code. Tritt das Ereignis ein, startet Claude Code Deinen Befehl und übergibt ihm auf der Standardeingabe ein JSON-Objekt mit allem, was gerade passiert: welches Tool aufgerufen wird, mit welchen Parametern, in welchem Ordner. Dein Skript liest das, tut seine Arbeit und meldet über den Exit-Code zurück, ob alles in Ordnung ist oder ob die Aktion gestoppt werden soll.
Die Doku listet inzwischen über dreißig Ereignisse. Für den Alltag reichen diese sechs:
| Ereignis | Wann es feuert | Kann blockieren |
|---|---|---|
PreToolUse | bevor ein Tool läuft, etwa Edit, Write oder Bash | ja, das Tool läuft dann nicht |
PostToolUse | nachdem ein Tool erfolgreich gelaufen ist | nein, kann Claude aber eine Rückmeldung geben |
Stop | wenn Claude mit seiner Antwort fertig ist | ja, Claude arbeitet dann weiter |
Notification | wenn Claude Code eine Benachrichtigung sendet | nein |
UserPromptSubmit | wenn Du einen Prompt abschickst, bevor Claude ihn sieht | ja |
SessionStart | beim Start, Fortsetzen oder nach dem Komprimieren | nein, kann aber Kontext einfügen |
Die vollständige Liste mit Ereignissen wie PreCompact, SubagentStop oder FileChanged steht in der Hooks reference.
Wo Hooks konfiguriert werden
Hooks stehen in denselben settings.json-Dateien wie die übrigen Einstellungen. Welche Datei Du nimmst, entscheidet über die Reichweite:
~/.claude/settings.jsongilt für alle Deine Projekte und bleibt auf Deinem Rechner..claude/settings.jsonim Projekt gilt nur dort und wird mit ins Repository eingecheckt, damit das ganze Team dieselben Hooks hat..claude/settings.local.jsongilt ebenfalls nur im Projekt, bleibt aber lokal.
Claude Code führt die Hooks aller Ebenen zusammen. Projektregeln wie Formatter und Dateisperren gehören deshalb ins Projekt, persönliche Dinge wie Benachrichtigungen in Deine Nutzerdatei.
Der Aufbau ist immer gleich: Unter hooks steht der Name des Ereignisses, darunter eine Liste von Gruppen mit einem matcher und den eigentlichen Befehlen.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "echo fertig"
}
]
}
]
}
}Der matcher filtert bei Tool-Ereignissen nach dem Tool-Namen. Edit|Write trifft genau diese beiden Tools, Groß- und Kleinschreibung zählt. Enthält der Wert andere Zeichen als Buchstaben, Ziffern, _, -, Leerzeichen, Komma und |, wertet Claude Code ihn als regulären Ausdruck, dann trifft Edit.* zum Beispiel auch NotebookEdit. Tools von MCP-Servern sprichst Du mit mcp__<server>__.* an, wobei <server> der Name ist, unter dem Du den Server eingetragen hast, wie in MCP-Server in Claude Code und Codex einrichten beschrieben. Ohne matcher feuert der Hook bei jedem Auftreten des Ereignisses.
Hat Deine Datei schon einen hooks-Block, ergänzt Du das neue Ereignis als weiteren Schlüssel darin, statt einen zweiten hooks-Block anzulegen. Änderungen erkennt Claude Code im laufenden Betrieb, und mit /hooks öffnest Du eine Übersicht, die jeden aktiven Hook samt Herkunftsdatei anzeigt.
Für die Beispiele brauchst Du jq, um das JSON auf der Standardeingabe auszulesen. Auf aktuellen macOS-Versionen liegt es schon unter /usr/bin/jq, unter Debian und Ubuntu installierst Du es mit sudo apt install jq. Längere Skripte legst Du im Projekt unter .claude/hooks/ ab.
mkdir -p .claude/hooksGetestet habe ich alle Skripte und Befehle unter macOS 27.2 mit der Bash 3.2 des Systems, jq 1.7.1, Node 24 und Prettier 3.10, indem ich ihnen nachgebaute Hook-Eingaben per Pipe übergeben habe, so wie es die Doku für die Fehlersuche empfiehlt. Die Benachrichtigung aus Beispiel 3 folgt der offiziellen Doku, sie ließ sich in meiner Testumgebung nicht auslösen.
Beispiel 1: Prettier nach jeder Änderung
Dieser Hook formatiert jede Datei, die Claude mit Edit oder Write anfasst. Installiere Prettier zuerst lokal im Projekt, damit der Aufruf schnell ist und alle im Team dieselbe Version nutzen:
npm install --save-dev prettierDanach trägst Du den Hook in .claude/settings.json im Projekt ein:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
}
]
}
]
}
}Der Befehl holt mit jq den Pfad der geänderten Datei aus tool_input.file_path und übergibt ihn an Prettier. --ignore-unknown sorgt dafür, dass Dateitypen, die Prettier nicht kennt, ohne Fehler übersprungen werden. Im Test wurde aus const a = {b:'x',c: 2} wie erwartet const a = { b: "x", c: 2 };. Ein erfolgreicher Hook zeigt im Chat nichts an, Du erkennst ihn also an der umformatierten Datei.
Beispiel 2: .env und andere sensible Dateien sperren
Dieser Hook verhindert, dass Claude mit Edit oder Write Geheimnisse, Schlüssel oder das Lockfile verändert. Lege die Datei .claude/hooks/schutz-dateien.sh an:
#!/bin/bash
# Blockiert Edit und Write auf sensible Dateien (PreToolUse).
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
NAME=$(basename "$FILE_PATH")
case "$NAME" in
.env.example)
exit 0
;;
.env|.env.*|*.pem|*.key|id_rsa*|id_ed25519*|package-lock.json)
echo "Gesperrt: $NAME ist eine geschützte Datei. Bitte nicht bearbeiten, sondern den Nutzer fragen." >&2
exit 2
;;
esac
case "$FILE_PATH" in
*/.git/*)
echo "Gesperrt: Dateien in .git/ werden nicht direkt bearbeitet." >&2
exit 2
;;
esac
exit 0Das Skript vergleicht den Dateinamen und nicht den ganzen Pfad. So bleibt src/environment.ts bearbeitbar, während .env und .env.local gesperrt sind, und die Vorlage .env.example ist ausdrücklich freigegeben. Exit-Code 2 stoppt das Tool, und der Text auf der Fehlerausgabe geht als Begründung an Claude, das daraufhin einen anderen Weg sucht oder Dich fragt. Mach das Skript ausführbar, sonst kann Claude Code es nicht starten:
chmod +x .claude/hooks/schutz-dateien.shDann registrierst Du es als PreToolUse-Hook in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/schutz-dateien.sh"
}
]
}
]
}
}$CLAUDE_PROJECT_DIR setzt Claude Code auf den Projektordner. Die Anführungszeichen darum halten den Pfad zusammen, falls er Leerzeichen enthält, was ich mit einem Ordner namens Mein Projekt geprüft habe. Fragst Du Claude danach, einen Kommentar in die .env zu schreiben, wird die Änderung abgelehnt.
Wichtig: Der Hook sieht nur die Tools Edit und Write. Über einen Shell-Befehl wie echo X >> .env käme Claude trotzdem an die Datei. Ergänze deshalb in derselben Datei Sperren unter permissions, etwa "deny": ["Read(./.env)", "Edit(./.env)"], und nutze für harte Grenzen die Sandbox von Claude Code.
Beispiel 3: Desktop-Benachrichtigung, wenn Claude wartet
Wenn Claude eine Freigabe braucht oder seit einer Minute auf Dich wartet, soll der Mac Bescheid geben. Das ist eine persönliche Vorliebe, also gehört der Hook in ~/.claude/settings.json:
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code wartet auf Dich\" with title \"Claude Code\"'"
}
]
}
]
}
}permission_prompt feuert laut Doku, wenn eine Freigabe-Abfrage etwa sechs Sekunden offen ist, idle_prompt, wenn Claude vor rund 60 Sekunden fertig geworden ist und Du seitdem nichts eingegeben hast. Lässt Du den matcher leer, bekommst Du jede Art von Benachrichtigung.
Erscheint nichts, fehlt meist die Mitteilungserlaubnis, denn osascript meldet sich über den Skripteditor. Führe einmal osascript -e 'display notification "Test"' im Terminal aus, öffne dann Systemeinstellungen > Mitteilungen, wähle Skripteditor und erlaube Mitteilungen. Unter Linux ersetzt Du den Befehl durch notify-send 'Claude Code' 'Claude Code wartet auf Dich'.
Beispiel 4: Tests laufen lassen, bevor Claude fertig meldet
Der Stop-Hook feuert, wenn Claude seine Antwort beenden will. Schlagen in diesem Moment die Tests fehl, schickt ihn der Hook mit der Fehlermeldung zurück an die Arbeit. Lege .claude/hooks/tests-vor-stop.sh an:
#!/bin/bash
# Lässt die Tests laufen, bevor Claude eine Antwort abschließt (Stop).
INPUT=$(cat)
# Schon einmal zurückgeschickt? Dann Claude stoppen lassen, sonst droht eine Schleife.
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0
fi
cd "$CLAUDE_PROJECT_DIR" || exit 0
# Nichts geändert? Dann gibt es nichts zu testen.
if [ -z "$(git status --porcelain)" ]; then
exit 0
fi
if ! OUTPUT=$(npm test 2>&1); then
echo "Die Tests schlagen fehl. Bitte die Ursache beheben, bevor Du fertig meldest:" >&2
echo "$OUTPUT" | tail -n 30 >&2
exit 2
fi
exit 0Das Feld stop_hook_active ist true, wenn Claude bereits wegen eines Stop-Hooks weiterarbeitet. Das Skript lässt Claude dann beim zweiten Mal stoppen, damit es sich nicht endlos im Kreis dreht. Die Prüfung mit git status --porcelain spart den Testlauf, wenn Claude nur eine Frage beantwortet und nichts geändert hat. Mach das Skript mit chmod +x .claude/hooks/tests-vor-stop.sh ausführbar und trag es ein:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tests-vor-stop.sh",
"timeout": 300
}
]
}
]
}
}Stop kennt keinen matcher, deshalb fehlt er hier. timeout begrenzt den Testlauf auf 300 Sekunden. In meinem Testprojekt mit node --test endete das Skript bei grünen Tests mit Exit-Code 0 und nach einem absichtlich eingebauten Fehler mit 2 und den letzten 30 Zeilen der Testausgabe. Ersetze npm test durch den Testbefehl Deines Projekts, etwa pytest oder go test ./....
Beispiel 5: Jeden Bash-Befehl protokollieren
Willst Du nachvollziehen, was Claude in der Shell ausgeführt hat, schreibt dieser Hook jeden Befehl mit Zeit und Ordner in eine Datei. Er gehört in ~/.claude/settings.json, damit er in allen Projekten greift:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -c '{zeit: (now | todate), ordner: .cwd, befehl: .tool_input.command}' >> ~/.claude/bash-log.jsonl"
}
]
}
]
}
}Weil der Hook an PreToolUse hängt, landen auch Befehle im Protokoll, die anschließend abgelehnt oder von einem anderen Hook blockiert werden. Jede Zeile ist ein eigenes JSON-Objekt, so bleiben auch mehrzeilige Befehle sauber getrennt. Die letzten 20 Einträge liest Du lesbar mit:
tail -n 20 ~/.claude/bash-log.jsonl | jq -r '"\(.zeit) \(.befehl)"'Die Datei wächst mit jedem Befehl. Lösch oder verschieb sie ab und zu, ein Neustart von Claude Code ist dafür nicht nötig.
Exit-Codes und Rückmeldung an Claude
Wie Claude Code auf Deinen Hook reagiert, hängt am Exit-Code:
| Exit-Code | Bedeutung | Was passiert |
|---|---|---|
0 | in Ordnung | Die Aktion läuft weiter. Bei PreToolUse ist das keine Freigabe, die normale Rechteabfrage folgt trotzdem. |
2 | blockieren | Bei PreToolUse läuft das Tool nicht, bei Stop arbeitet Claude weiter, bei PostToolUse sieht Claude die Meldung, die Änderung ist aber schon passiert. Die Fehlerausgabe wird zur Begründung. |
| jeder andere | Fehler im Hook | Claude Code zeigt einen Hinweis, die Aktion läuft trotzdem weiter. |
Die häufigste Falle steckt in der letzten Zeile: exit 1 blockiert nichts. Ein Sperr-Skript muss mit 2 enden, sonst wirkt es nur wie eine Warnung.
Feiner steuerst Du mit JSON. Dann endet der Hook mit 0 und gibt ein Objekt auf der Standardausgabe aus. Dieses Skript lehnt einen Force-Push ab und sagt Claude, was es stattdessen tun soll:
#!/bin/bash
# Lehnt git push --force ab und sagt Claude, warum (PreToolUse, Bash).
COMMAND=$(jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -Eq 'git push.*(--force|-f( |$))'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Force-Push ist in diesem Projekt verboten. Nutze git push ohne --force."
}
}'
fi
exit 0permissionDecision kennt allow, deny, ask und defer. Ein deny gilt in jedem Rechtemodus, auch mit --dangerously-skip-permissions. Das Muster trifft übrigens auch --force-with-lease; willst Du das erlauben, verfeinerst Du den regulären Ausdruck. Mit dem Feld if startest Du das Skript nur für passende Befehle:
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(git push *)",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/kein-force-push.sh"
}
]
}Diesen Block setzt Du als weitere Gruppe in die PreToolUse-Liste. Erzeuge JSON immer mit jq statt mit zusammengesetzten Zeichenketten, dann stimmen Anführungszeichen und Sonderzeichen. Und gib in einem Hook entweder Exit-Code 2 oder JSON zurück, nicht beides.
Sicherheit: Hooks laufen mit Deinen Rechten
Ein Hook ist ein ganz normaler Shell-Befehl. Er darf alles, was Dein Benutzerkonto darf, also auch Dateien löschen oder Daten ins Netz schicken. Daraus folgen drei Regeln.
- Fremde Repositories prüfen. Im interaktiven Modus hält Claude Code alle Hooks zurück, bis Du dem Ordner im Vertrauensdialog zustimmst. Im Skriptmodus mit
claude -pgibt es diesen Dialog nicht, die Hooks aus der.claude/settings.jsoneines geklonten Repositorys laufen dann sofort. Wer Claude Code wie in Claude Code automatisch ausführen: Headless mit launchd unbeaufsichtigt startet, schaut vorher in den.claude-Ordner oder schaltet Hooks für den Lauf mit--settings '{"disableAllHooks": true}'ab. - Sauber programmieren. Setz Variablen immer in Anführungszeichen (
"$FILE_PATH", nicht$FILE_PATH), verwende absolute Pfade oder$CLAUDE_PROJECT_DIRund vertraue den Eingaben nicht blind, denn Dateipfade und Befehle stammen letztlich vom Modell. - Hooks nicht als einzige Grenze nutzen. Ein abgestürzter Sperr-Hook lässt die Aktion standardmäßig durch. Für Regeln, die ausnahmslos gelten müssen, setzt Du zusätzlich
"onFailure": "block"am Hook und Sperren unterpermissions.deny.
Fehlersuche
- Hook feuert nicht: Öffne
/hooksund prüf, ob er unter dem richtigen Ereignis steht. Dermatcherunterscheidet Groß- und Kleinschreibung,edittrifft also nichts. Erscheint der Hook nach einer Änderung nicht, starte die Sitzung neu. - „hook error” im Verlauf: Teste das Skript von Hand mit einer nachgebauten Eingabe und schau Dir den Exit-Code an:
echo '{"tool_name":"Edit","tool_input":{"file_path":".env"}}' | .claude/hooks/schutz-dateien.shund danachecho $?. Fehlt die Ausführbarkeit, hilftchmod +x, bei „jq: command not found” die Installation vonjq. - JSON wirkt nicht: Gibt Deine Shell-Konfiguration beim Start Text aus, steht der vor dem JSON, und Claude Code liest die Ausgabe als reinen Text. Prüf außerdem, ob
permissionDecisioninnerhalb vonhookSpecificOutputsteht. - Was hat der Hook getan?
Ctrl + Oöffnet die Verlaufsansicht mit den Meldungen der Hooks. Ausführliche Protokolle schreibt Claude Code, wenn Du es mitclaude --debug-file /tmp/claude.logstartest, die Datei verfolgst Du in einem zweiten Terminal mittail -f /tmp/claude.log.
Hooks, CLAUDE.md und Berechtigungen richtig aufteilen
Hooks sind das Werkzeug für alles, was ohne Ausnahme bei einem bestimmten Ereignis passieren muss. Was Claude wissen sollte, um gute Entscheidungen zu treffen, bleibt in der CLAUDE.md, und was Claude nie tun darf, sperrst Du über Berechtigungen. Wie Du die CLAUDE.md schlank hältst und was dort wirklich hineingehört, steht in CLAUDE.md für Claude Code: was rein gehört, was nicht. Fang mit einem Hook an, am besten dem Formatter oder der Dateisperre, und ergänze weitere erst, wenn Du merkst, dass Du Claude dieselbe Sache zum dritten Mal sagst.
Weiterlesen.
-
KICLAUDE.md für Claude Code: was rein gehört, was nicht
So schreibst Du eine CLAUDE.md, an die sich Claude Code hält: was hinein gehört, was nicht, Ladeorte, Vorlage und ein echtes Beispiel.
Nathan Base -
KIClaude Code automatisch ausführen: Headless mit launchd
Claude Code ohne Chatfenster: mit claude -p, festen Werkzeugrechten und launchd jeden Morgen einen Projektbericht erstellen und aufs Handy schicken.
Nathan Base -
KIMCP-Server in Claude Code und Codex einrichten
MCP-Server in Claude Code und Codex CLI hinzufügen, API-Schlüssel sicher übergeben und die typischen Fehler wie Timeouts und fehlende Anmeldung beheben.
Nathan Base -
KIAnleitung: Claude Code auf dem Mac installieren & nutzen
Claude Code auf dem Mac installieren, anmelden und sinnvoll nutzen: die wichtigsten Konzepte und drei Alltags-Workflows jenseits vom Programmieren.
Nathan Base -
KIClaude Code: Kontext, /compact, /clear und Subagents
Warum lange Sitzungen in Claude Code schlechter werden und wie Du mit /context, /compact, /clear und Subagents Kontext und Nutzungslimit im Griff hältst.
Nathan Base -
KIMCP-Server in Python bauen: Claude liest Home Assistant
Eigenen MCP-Server in Python bauen: mit SDK 2, uv und Inspector Tools und eine Ressource schreiben und in Claude Code und Claude Desktop nutzen.
Nathan Base