So nutzen Sie Hooks in Claude Code

Manches soll jedes Mal passieren, etwa dass eine Datei formatiert wird, nachdem Claude sie bearbeitet hat, oder dass Sie einen Hinweis bekommen, wenn Claude auf Sie wartet, und zwar ohne darauf zu hoffen, dass Claude daran denkt. Genau dafür gibt es Hooks. Diese Anleitung erklärt, was sie sind, führt durch einen ersten Hook und zeigt, wo sie hingehören.

Aktualisiert am 30. Oktober 2026

Kurz gesagt: Ein Hook ist ein Shell-Befehl, den Claude Code automatisch an einem festen Punkt ausführt, zum Beispiel bevor ein Werkzeug läuft, nachdem eine Datei bearbeitet wurde oder wenn Claude Ihre Eingabe braucht. Sie tragen Hooks unter dem Schlüssel hooks in eine Einstellungsdatei ein, etwa ~/.claude/settings.json (alle Projekte) oder .claude/settings.json (ein Projekt), und tippen dann /hooks, um zu prüfen, dass Claude Code sie erkennt.

Eventnamen, Speicherorte und Verhalten stammen aus der Claude-Code-Dokumentation von Anthropic, Stand Oktober 2026. Claude Code wird oft aktualisiert; führen Sie claude update aus, wenn etwas fehlt.

Was Hooks sind und warum sie helfen

Anweisungen in einem Prompt oder in einer CLAUDE.md-Datei sind Vorschläge: Claude folgt ihnen meist, entscheidet aber selbst. Ein Hook ist anders. Claude Code selbst führt Ihren Befehl aus, sobald das Event eintritt, die Aktion ist also deterministisch. Typische Einsätze aus der Anleitung von Anthropic:

Benachrichtigungen, wenn Claude auf eine Berechtigung oder Ihre Antwort wartet.
Automatisches Formatieren jeder Datei, nachdem Claude sie bearbeitet oder geschrieben hat.
Blockieren von Änderungen an sensiblen Dateien wie .env oder allem in .git/.
Kontext ergänzen, etwa Claude nach dem Komprimieren des Gesprächs an Projektkonventionen erinnern.

Zu den meistgenutzten Events gehören SessionStart (eine Sitzung beginnt oder wird fortgesetzt), UserPromptSubmit (Sie senden einen Prompt), PreToolUse (vor einem Werkzeugaufruf, den es blockieren kann), PostToolUse (nach einem erfolgreichen Werkzeugaufruf), Notification, Stop (Claude ist mit der Antwort fertig), PreCompact und SessionEnd. Die vollständige Liste in der Hooks-Referenz ist deutlich länger.

Ihr erster Hook: eine Desktop-Benachrichtigung

Dieses Beispiel, angelehnt an die Schritt-für-Schritt-Anleitung von Anthropic, meldet sich unter macOS, sobald Claude Code Ihre Aufmerksamkeit braucht.

Öffnen Sie ~/.claude/settings.json in einem Texteditor. Legen Sie die Datei an, falls es sie nicht gibt.
Fügen Sie ein Objekt hooks mit einem Eintrag Notification hinzu. Darin steht eine Liste von Matcher-Gruppen; jede hat einen matcher (als leere Zeichenkette lassen, damit er bei jeder Benachrichtigung auslöst) und eine Liste hooks mit einem Element vom Typ "type": "command".
Setzen Sie als Befehl osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. Unter Linux verwendet das Beispiel von Anthropic stattdessen notify-send. Denken Sie daran, die inneren doppelten Anführungszeichen im JSON zu maskieren.
Hat die Datei schon einen Schlüssel hooks, ergänzen Sie Notification neben den vorhandenen Events, statt das ganze Objekt zu ersetzen.
Tippen Sie in Claude Code /hooks. Die Hook-Übersicht sollte Ihren neuen Hook unter Notification anzeigen. Mit Esc gehen Sie zurück.
Bitten Sie Claude um etwas, das eine Berechtigung braucht, und wechseln Sie in ein anderes Fenster. Eine Benachrichtigung sollte erscheinen.

Damit der Hook nur bei bestimmten Benachrichtigungen auslöst, setzen Sie den Matcher auf einen Typ wie permission_prompt (eine Berechtigungsrückfrage wartet seit etwa sechs Sekunden) oder idle_prompt (Claude ist fertig und Sie haben etwa eine Minute lang nichts getippt).

Ein zweites Beispiel: Dateien nach Änderungen formatieren

Für einen Projekt-Hook kommt die Konfiguration in .claude/settings.json im Projektstamm. Verwenden Sie das Event PostToolUse mit dem Matcher Edit|Write, damit er nur nach Werkzeugen zum Bearbeiten von Dateien läuft. Der Beispielbefehl von Anthropic liest den Pfad der bearbeiteten Datei aus dem JSON, das Claude Code über die Standardeingabe übergibt, und reicht ihn an Prettier weiter: jq -r '.tool_input.file_path' | xargs npx prettier --write. Dafür muss jq installiert sein. Ein erfolgreicher Hook zeigt im Gespräch nichts an; Sie sehen nur, dass die Datei neu formatiert ist.

Wo Hooks konfiguriert werden

Ort	Gilt für	Geteilt?
`~/.claude/settings.json`	Alle Ihre Projekte	Nein, nur Ihr Rechner
`.claude/settings.json`	Ein Projekt	Ja, kann committet werden
`.claude/settings.local.json`	Ein Projekt	Nein, bleibt außerhalb von git
Verwaltete Richtlinieneinstellungen	Ganze Organisation	Von Admins festgelegt
`hooks/hooks.json` eines Plugins	Solange das Plugin aktiviert ist	Im Plugin enthalten
Skill-Frontmatter	Den Rest der Sitzung, nachdem der Skill aufgerufen wurde	In der Skill-Datei
Subagent-Frontmatter	Solange dieser Subagent läuft	In der Subagent-Datei

Um Hooks abzuschalten, setzen Sie "disableAllHooks": true in einer Einstellungsdatei. Hooks aus verwalteten Einstellungen laufen weiter, sofern es nicht auch dort gesetzt ist.

Wie ein Hook antwortet

Tritt ein Event ein, schickt Claude Code die Event-Details als JSON an die Standardeingabe Ihres Befehls. Ihr Befehl antwortet mit seinem Exit-Code:

Exit 0: weitermachen. Bei manchen Events, etwa SessionStart, wird einfacher Text auf der Standardausgabe zu Claudes Kontext hinzugefügt.
Exit 2: die Aktion blockieren, sofern das Event das zulässt. Schreiben Sie den Grund auf die Standardfehlerausgabe; bei PreToolUse bekommt Claude ihn und kann umsteuern.
Andere Codes: werden meist als nicht blockierender Fehler behandelt; die Aktion läuft weiter und das Transkript zeigt einen Hook-Fehler.

Für genauere Steuerung beenden Sie mit Exit 0 und geben stattdessen ein JSON-Objekt aus. Wählen Sie pro Hook einen der beiden Wege.

Gut zu wissen

Befehls-Hooks können selbst keine Slash-Befehle ausführen und keine Werkzeuge aufrufen.
Das Standard-Timeout für Befehls-Hooks beträgt 10 Minuten, bei einigen Events weniger; mit timeout (in Sekunden) ändern Sie es pro Hook.
PostToolUse kann nichts rückgängig machen, weil das Werkzeug bereits gelaufen ist. Um eine Aktion zu verhindern, nutzen Sie PreToolUse.
Stop löst jedes Mal aus, wenn Claude eine Antwort beendet, nicht nur, wenn eine Aufgabe erledigt ist.

Wenn es nicht funktioniert

Der Hook löst nie aus: Führen Sie /hooks aus und prüfen Sie, ob er unter dem richtigen Event steht. Matcher unterscheiden Groß- und Kleinschreibung und müssen genau zum Werkzeugnamen passen, zum Beispiel Edit, nicht edit.
„/hooks“ zeigt nichts: Prüfen Sie, ob das JSON gültig ist (keine abschließenden Kommas oder Kommentare) und in der richtigen Datei steht. Änderungen werden normalerweise automatisch übernommen; falls nicht, starten Sie die Sitzung neu.
„hook error“ im Transkript: Testen Sie das Skript, indem Sie Beispiel-JSON hineinleiten und echo $? prüfen. Verwenden Sie für Skripte absolute Pfade oder $CLAUDE_PROJECT_DIR, installieren Sie jq, falls es fehlt, und machen Sie Skripte mit chmod +x ausführbar.
Keine macOS-Benachrichtigung: Führen Sie den osascript-Befehl einmal im Terminal aus und aktivieren Sie dann Allow Notifications (Mitteilungen erlauben) für Script Editor (Skripteditor) unter System Settings > Notifications (Systemeinstellungen > Mitteilungen).

Festhalten, was jede Sitzung offen lässt

Das Workbranch-Plugin für Claude Code nutzt eine Zusammenfassung beim Sitzungsstart: In einem Ordner, der mit einem Workbranch-Projekt verknüpft ist, zeigt es zu Beginn einer Sitzung, was noch offen ist, und wenn Sie „save this to Workbranch“ (speichere das in Workbranch) sagen, legt es die Aufgaben, Entscheidungen und offenen Fragen der Sitzung in diesem Projekt ab. Mehr dazu unter Workbranch für Claude. Neu bei Claude Code? Beginnen Sie mit dem Einstieg in Claude Code.

Quellen

Use Claude Code with your Pro or Max plan (Claude Help Center, geprüft am 30. Oktober 2026)
Automate actions with hooks (Claude Code docs, geprüft am 30. Oktober 2026)

Häufige Fragen

Kann Claude einen Hook für mich schreiben?

Ja. Laut der Anleitung von Anthropic können Sie den gewünschten Hook im Prompt von Claude Code beschreiben und Claude bitten, ihn zu Ihren Einstellungen hinzuzufügen. Prüfen Sie das Ergebnis anschließend mit /hooks.

Kann ein Hook Claude auch im Bypass-Modus stoppen?

Ein PreToolUse-Hook, der eine deny-Entscheidung zurückgibt, blockiert das Werkzeug in jedem Berechtigungsmodus, auch in bypassPermissions. Deshalb eignen sich Hooks für Regeln, die man nicht durch einen Moduswechsel aushebeln kann.

Gibt es Hooks, die statt eines Skripts ein Modell nutzen?

Ja. Neben Shell-Befehlen kann ein Hook eine HTTP-Anfrage, ein MCP-Werkzeugaufruf, ein einzelner Prompt, den ein Claude-Modell auswertet, oder ein experimenteller Agent-Hook mit Werkzeugzugriff sein.