Ratgeber · 10. November 2026 · 11 Min. Lesezeit

Claude Code Hooks: Was sie sind und wie du sie einrichtest

Claude Code Hooks einfach erklärt: wo sie stehen, welche Events es gibt, wie Exit-Code 2 Aktionen blockiert und drei Hooks, die du heute einrichten kannst.

Das Wichtigste in Kürze

  • Ein Hook ist ein Befehl, den Claude Code an einem festen Punkt im Ablauf ausführt, also fest und verlässlich statt als Bitte an das Modell.
  • Hooks stehen in einem hooks-Block in ~/.claude/settings.json (für alle Projekte), .claude/settings.json (fürs Team) oder .claude/settings.local.json (nur für dich im Projekt).
  • Die wichtigsten Events sind PreToolUse, PostToolUse, Notification, Stop, SessionStart und UserPromptSubmit, mit einem matcher grenzt du ein, für welche Tools der Hook gilt.
  • Exit-Code 2 blockiert die Aktion und gibt Claude den Grund aus stderr zurück.
  • Hooks können weitreichende Aktionen ausführen, also baust du nur Hooks ein, deren Code du vollständig verstanden hast.

Claude Code Hooks sind kleine Shell-Befehle, die Claude Code selbst an festen Punkten ausführt, zum Beispiel bevor eine Datei bearbeitet wird, nachdem ein Tool gelaufen ist oder wenn Claude auf deine Eingabe wartet. Du trägst sie in einen hooks-Block in deiner settings.json ein, und ab dann passieren diese Dinge jedes Mal, ohne dass das Modell daran denken muss. Endet ein Hook mit dem Exit-Code 2, wird die Aktion sogar blockiert. Hier zeige ich dir, wo Hooks stehen, welche Events es gibt und wie du drei Hooks einrichtest, die ich selbst für die sinnvollsten zum Starten halte: eine Benachrichtigung, einen Schutz für deine .env und automatisches Formatieren nach jeder Bearbeitung mit Edit oder Write.

Was sind Claude Code Hooks und wofür brauche ich sie?

Wenn du länger mit Claude Code arbeitest, kennst du das: Du schreibst in deine CLAUDE.md, dass Claude nie die .env anfassen soll, und meistens klappt das auch. Aber eben nur meistens. Die CLAUDE.md ist eine Anweisung an das Modell, und ein Modell kann eine Anweisung übersehen, vor allem in einer langen Sitzung.

An dieser Stelle kommen Hooks ins Spiel. Laut dem offiziellen Hooks-Guide sind Hooks von dir festgelegte Shell-Befehle, die Claude Code an bestimmten Punkten in seinem Ablauf ausführt. Der entscheidende Unterschied: Nicht das Modell entscheidet, ob der Hook läuft, sondern Claude Code selbst. Das Modell kann ihn nicht vergessen, nicht wegdiskutieren und nicht überspringen.

Typische Fälle, für die ich Hooks benutze oder in der Community immer wieder sehe:

  • eine Benachrichtigung auf dem Mac, sobald Claude auf dich wartet, damit du nicht alle zwei Minuten ins Terminal schauen musst
  • automatisches Formatieren mit Prettier nach jeder Dateiänderung
  • ein Schutz, der Änderungen an .env, package-lock.json oder dem .git/-Ordner einfach blockiert
  • Kontext, der nach einer Komprimierung der Sitzung automatisch wieder reingeladen wird
  • ein Protokoll, welche Befehle Claude in einer Sitzung ausgeführt hat

Was ist der Unterschied zwischen Hook, CLAUDE.md und Skill?

Die drei werden ständig verwechselt, dabei lösen sie ganz unterschiedliche Probleme. Ich erklär es immer so: Die CLAUDE.md sagt Claude, wie ihr zusammenarbeitet. Ein Skill sagt Claude, wie eine bestimmte Aufgabe geht. Und ein Hook sorgt dafür, dass bestimmte Dinge einfach passieren oder eben nicht passieren können.

WerkzeugWer setzt es umWofür
CLAUDE.mddas Modell, das die Datei liestRegeln und Befehle, die fast immer gelten
Skilldas Modell, wenn es den Skill lädtlängere Abläufe für bestimmte Aufgaben
HookClaude Code selbst, ohne das ModellDinge, die jedes Mal passieren müssen oder nie passieren dürfen

Die Faustregel ist ziemlich einfach: Wenn eine Regel nie gebrochen werden darf, gehört sie in einen Hook. Wenn sie meistens gelten soll und Claude sie mitdenken muss, gehört sie in die CLAUDE.md.

Wo trage ich einen Hook ein und welche Events gibt es?

Hooks stehen in einer Einstellungsdatei von Claude Code, und zwar in einem Block namens hooks. Laut der Doku zu den Einstellungen gibt es dafür mehrere Orte:

DateiGilt für
~/.claude/settings.jsondich, in all deinen Projekten
.claude/settings.jsonalle im Projekt, du committest die Datei, damit dein Team dieselben Hooks bekommt
.claude/settings.local.jsonnur dich in diesem Projekt, bleibt aus Git raus

Dazu kommen noch verwaltete Einstellungen, die eine Firma zentral setzen kann. Gibt es Widersprüche, gewinnt in dieser Reihenfolge: verwaltete Einstellungen, dann Kommandozeile, dann die lokale Projektdatei, dann die geteilte Projektdatei und zuletzt deine Benutzerdatei. Eine schöne Kleinigkeit: Laut Doku lädt Claude Code Änderungen an Hooks in einer laufenden Sitzung neu, du musst also nicht jedes Mal neu starten.

Jeder Hook hängt an einem Event, also an einem Zeitpunkt im Ablauf. Die Hooks-Referenz listet viele Events auf. Am Anfang brauchst du davon aber nur eine Handvoll:

  • SessionStart: wenn eine Sitzung startet oder fortgesetzt wird
  • UserPromptSubmit: wenn du einen Prompt abschickst, bevor Claude ihn bearbeitet
  • PreToolUse: bevor Claude ein Tool benutzt, zum Beispiel eine Datei bearbeitet oder einen Befehl ausführt; hier kannst du blockieren
  • PostToolUse: nachdem ein Tool erfolgreich gelaufen ist
  • Notification: wenn Claude Code dir eine Benachrichtigung schickt, etwa weil es auf dich wartet
  • Stop: wenn Claude mit seiner Antwort fertig ist
  • PreCompact und SessionEnd: vor einer Komprimierung und am Ende einer Sitzung

Mit dem matcher legst du fest, für welche Tools ein Hook gilt. Edit|Write heißt zum Beispiel: nur, wenn Claude eine Datei bearbeitet oder schreibt. Ein leerer Matcher gilt für alles.

Was der Hook dann tut, bestimmt sein Typ. Der häufigste ist command, also ein Shell-Befehl. Laut Referenz gibt es außerdem http, mcp_tool, prompt und agent; für den Anfang reicht command völlig.

Wie richte ich meinen ersten Hook ein (Benachrichtigung, wenn Claude auf mich wartet)?

Das ist der Hook, mit dem ich jedem empfehle anzufangen, weil er nichts kaputt machen kann und du sofort merkst, dass es funktioniert. Er schickt dir eine Mitteilung auf dem Mac, sobald Claude auf deine Eingabe wartet. Öffne ~/.claude/settings.json und trag diesen Block ein (wenn die Datei schon andere Einstellungen hat, kommt hooks einfach als weiterer Schlüssel dazu):

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code wartet auf dich\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Der Aufbau ist bei jedem Hook gleich: Event, darunter eine Liste mit matcher und darunter die eigentlichen hooks mit Typ und Befehl. osascript ist das Mac-Werkzeug, das die Mitteilung anzeigt. Unter Linux oder Windows brauchst du an dieser Stelle einen anderen Befehl, das Prinzip bleibt dasselbe.

Danach tippst du in Claude Code /hooks. Laut Hooks-Guide öffnet das eine Übersicht, in der du siehst, welche Hooks registriert sind. Steht dein Notification-Hook dort, gib Claude eine Aufgabe, bei der es dich um eine Erlaubnis fragt, wechsel in ein anderes Fenster und warte auf die Mitteilung.

Ich muss ehrlich sagen, dass genau dieser kleine Hook bei mir am meisten verändert hat. Seit ich ihn habe, lasse ich Claude in Ruhe arbeiten und mache in der Zeit etwas anderes, statt ständig nachzuschauen, ob es schon fertig ist.

Wie blockiere ich mit einem Hook Änderungen an .env und anderen geschützten Dateien?

Hier setzt du zum ersten Mal eine Regel technisch durch, statt sie nur als Anweisung an das Modell zu formulieren. Ein PreToolUse-Hook läuft, bevor Claude eine Datei bearbeitet. Endet er mit Exit-Code 2, wird die Bearbeitung blockiert, und was dein Skript nach stderr schreibt, bekommt Claude als Begründung zurück.

Dafür muss der Hook wissen, welche Datei Claude gerade anfassen will. Laut Hooks-Referenz bekommt jeder Hook dafür ein JSON über stdin, unter anderem mit session_id, cwd, hook_event_name, tool_name und tool_input. Den Dateipfad liest du mit jq aus, einem kleinen Werkzeug für JSON auf der Kommandozeile. Das musst du einmal installieren, auf dem Mac zum Beispiel mit brew install jq, sonst laufen die Beispiele nicht.

Leg im Projekt die Datei .claude/hooks/protect-files.sh an:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH ist geschützt ($pattern)" >&2
    exit 2
  fi
done

exit 0

Mach das Skript ausführbar mit chmod +x .claude/hooks/protect-files.sh und registrier es in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Wenn Claude jetzt versucht, deine .env zu ändern, kommt die Änderung gar nicht erst durch. Claude sieht die Meldung und sucht sich einen anderen Weg oder fragt dich. Weil die Datei im Projekt liegt und du .claude/settings.json committest, bekommt dein ganzes Team denselben Schutz.

Wichtig ist der Exit-Code, weil hier die meisten Fehler passieren. Blockiert wird die Aktion nur, wenn dein Skript mit 2 endet; dann gibt Claude Code den Text aus stderr als Grund an Claude zurück. Wer schützen will, muss also bewusst mit 2 aussteigen.

Wie formatiere ich Code automatisch nach jeder Bearbeitung?

Der dritte Hook ist einer, den ich in fast jedem Webprojekt drin habe: Nach jeder Bearbeitung mit Edit oder Write formatiert Prettier die Datei, sodass Claude und du nie wieder über Einrückungen und Anführungszeichen diskutieren müsst. Der Hooks-Guide zeigt dafür einen PostToolUse-Hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

jq holt wieder den Dateipfad aus dem JSON, und xargs gibt ihn an Prettier weiter. Voraussetzung ist natürlich, dass Prettier in deinem Projekt eingerichtet ist. Du kannst an derselben Stelle genauso gut einen Linter oder einen anderen Formatierer aufrufen, der Aufbau bleibt gleich.

Ein Tipp aus der Praxis: Halte PostToolUse-Hooks schnell. Sie laufen nach jeder einzelnen Änderung, und wenn da ein Befehl drinsteht, der zehn Sekunden braucht, merkst du das bei einer Aufgabe mit fünfzig Änderungen ziemlich deutlich. Lange Prüfungen wie die komplette Testsuite gehören eher ans Ende, zum Beispiel in einen Stop-Hook.

Noch einer, der dir viel Ärger erspart: Ein SessionStart-Hook mit dem Matcher compact läuft laut Guide nach jeder Komprimierung der Sitzung. Damit kannst du wichtigen Kontext automatisch wieder reinladen, statt dass er nach dem Komprimieren einfach weg ist.

Sind Hooks sicher und was tun, wenn ein Hook nicht auslöst?

Hooks sind mächtig, und genau deshalb solltest du sie ernst nehmen. Ein Hook ist ein Shell-Befehl auf deinem Rechner und kann weitreichende Aktionen ausführen, zum Beispiel Dateien löschen. Kopier deshalb nie einen Hook aus dem Netz, ohne jede Zeile verstanden zu haben.

Ein Detail, das viele nicht kennen: Geteilte Hooks aus einem Projekt können erst greifen, nachdem du den Ordner im Vertrauensdialog bestätigt hast. Prüf deshalb bei fremden Projekten zuerst die Einstellungen. Wenn du ein fremdes Repo klonst und direkt mit claude -p loslegst, schau vorher in .claude/settings.json, welche Hooks dort stehen.

Die Referenz nennt außerdem ein paar Grundregeln für eigene Hook-Skripte, an die ich mich halte:

  • Variablen immer in Anführungszeichen setzen, also "$FILE_PATH" statt $FILE_PATH
  • Pfade mit .. blockieren, damit niemand aus dem Projektordner ausbricht
  • Pfade immer vollständig angeben, zum Beispiel über $CLAUDE_PROJECT_DIR
  • sensible Dateien wie .env oder Schlüssel überspringen statt sie zu lesen

Wenn ein Hook nicht auslöst, gehe ich immer in derselben Reihenfolge vor. Erstens /hooks öffnen und schauen, ob er überhaupt registriert ist. Fehlt er dort, stimmt meistens etwas am JSON nicht, oft ein fehlendes Komma oder eine falsche Klammer. Zweitens den matcher prüfen: Groß- und Kleinschreibung zählt, edit ist nicht Edit. Drittens das Skript von Hand testen, indem du ein kleines JSON hineinschickst, zum Beispiel echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protect-files.sh; echo $?. Kommt da 2 raus, funktioniert das Skript, und der Fehler liegt in der Einstellung. Viertens prüfen, ob das Skript ausführbar ist und ob jq installiert ist.

Und wenn du mal schnell ohne Hooks arbeiten willst, um herauszufinden, ob ein Hook das Problem ist: Laut Referenz schaltet claude --settings '{"disableAllHooks": true}' alle Hooks für diesen einen Lauf ab.

Häufige Fragen

Was sind Claude Code Hooks?

Claude Code Hooks sind Shell-Befehle, die Claude Code an festen Punkten im Ablauf selbst ausführt, zum Beispiel vor oder nach einer Dateiänderung. Anders als Anweisungen in der CLAUDE.md hängen sie nicht davon ab, dass das Modell sich erinnert, sie laufen jedes Mal.

Wo werden Claude Code Hooks gespeichert?

Hooks stehen in einem hooks-Block in einer Einstellungsdatei von Claude Code. Für alle Projekte ist das ~/.claude/settings.json, fürs Team .claude/settings.json im Projekt und nur für dich .claude/settings.local.json.

Wie blockiere ich eine Aktion mit einem Hook?

Du schreibst einen PreToolUse-Hook, der mit Exit-Code 2 endet, wenn die Aktion nicht passieren soll. Claude Code bricht die Aktion dann ab und gibt Claude den Text aus stderr als Grund zurück.

Was bedeuten die Exit-Codes bei Hooks?

Exit-Code 2 blockiert die Aktion und gibt Claude den Grund aus stderr zurück. Ein Schutz-Hook muss also bewusst mit 2 enden.

Wie sehe ich, welche Hooks aktiv sind?

Tipp in Claude Code /hooks ein. Das öffnet eine Übersicht mit allen registrierten Hooks, und dort siehst du sofort, ob dein neuer Hook angekommen ist.

Muss ich Claude Code nach einer Änderung an den Hooks neu starten?

Nein, Claude Code lädt Änderungen an Hooks in einer laufenden Sitzung neu. Wenn ein Hook trotzdem fehlt, prüf mit /hooks, ob dein JSON gültig ist.

Sind Hooks gefährlich?

Hooks können weitreichende Aktionen ausführen. Sie sind sicher, solange du nur Hooks einbaust, deren Code du verstehst, und bei fremden Projekten vorher in die .claude/settings.json schaust.

Fazit

Hooks sind der Schritt von „Claude, bitte denk daran“ zu „das passiert jetzt einfach“. Fang klein an: Richte heute den Notification-Hook ein, prüf mit /hooks, dass er da ist, und bau danach den Schutz für deine .env mit Exit-Code 2 und das automatische Formatieren nach jeder Bearbeitung. Damit hast du in einer halben Stunde ein Setup, das Claude ruhiger arbeiten lässt und dir ein paar richtig unangenehme Fehler erspart. Wenn du deine Hooks mit anderen Buildern weiterentwickeln willst, komm in den KI Agenten Club.

KI Agenten Club

Du willst nicht nur lesen, sondern bauen?

Im KI Agenten Club baust du mit Vishal KI-Agenten für dein Business. Kurse, fertige Skills und Leute, die dasselbe bauen.

Zum KI Agenten Club

Das könnte dich auch interessieren