Claude Code Hooks in 2026: Ein praktischer Leitfaden

Claude Code Hooks sind benutzerdefinierte Shell-Befehle, HTTP-Aufrufe oder LLM-Prompts, die an festen Punkten im Lebenszyklus von Claude Code automatisch ausgeführt werden: bevor ein Tool läuft, nachdem eine Datei bearbeitet wurde, wenn eine Sitzung beginnt oder wenn Claude einen Turn abschließt. Es gibt sie, um bestimmte Aktionen deterministisch zu machen. Statt zu hoffen, dass das Modell daran denkt, deinen Code zu formatieren oder einen destruktiven Befehl auszulassen, erzwingt ein Hook die Regel jedes Mal. Dieser Leitfaden behandelt, was Claude Code Hooks sind, die Events, bei denen sie auslösen, wie du deinen ersten konfigurierst, ein funktionierendes Beispiel zum Kopieren und wann du zu einem Hook statt zu einem Skill oder Subagenten greifen solltest.

Wir betreiben die Content-Pipeline dieser Website mit Claude Code, daher sind Hooks Teil unseres täglichen Toolsets. Die folgenden Muster sind die, die man zuerst lernen sollte.

Was sind Claude Code Hooks?

Ein Hook ist eine Regel, die durch Code statt durch Anweisungen erzwungen wird. Alles, was du in eine CLAUDE.md-Datei oder einen Prompt schreibst, ist ein Vorschlag, den das Modell prinzipiell ignorieren oder vergessen kann. Ein Hook ist nicht optional: Wenn das Event auslöst, läuft der Hook, Punkt. Laut Anthropics Hooks-Dokumentation ist ein Hook „ein benutzerdefinierter Shell-Befehl, HTTP-Endpunkt oder LLM-Prompt, der an bestimmten Punkten im Lebenszyklus von Claude Code automatisch ausgeführt wird“.

Diese Unterscheidung ist der springende Punkt. Wenn dein Linter nach jeder Bearbeitung laufen soll, funktioniert ein Prompt mit „führe immer den Linter aus“ meistens; ein PostToolUse-Hook führt ihn jedes Mal aus, ohne vom Urteil des Modells abhängig zu sein. Hooks sind die Art, wie du aus „Claude macht normalerweise X“ ein „Claude macht immer X“ machst. Häufige Aufgaben sind das automatische Formatieren von Dateien, das Blockieren riskanter Shell-Befehle, das Senden einer Desktop-Benachrichtigung, wenn Claude eine Eingabe benötigt, und das Einspeisen von frischem Kontext (etwa des aktuellen Git-Branches) zu Beginn einer Sitzung.

Wann Hooks auslösen: die Lebenszyklus-Events

Claude Code stellt mehr als dreißig Lebenszyklus-Events bereit, in die du dich einklinken kannst, aber eine Handvoll deckt fast jeden realen Anwendungsfall ab. Jedes Event übergibt deinem Hook eine JSON-Payload über stdin, die beschreibt, was gerade passiert.

Event	Löst aus, wenn	Typische Nutzung
UserPromptSubmit	Du einen Prompt sendest, bevor Claude ihn liest	Kontext einspeisen, Geheimnisse in einem Prompt blockieren
PreToolUse	Bevor irgendein Tool läuft	Einen Befehl blockieren oder freigeben; kann die Aktion verweigern
PostToolUse	Nachdem ein Tool erfolgreich war	Code formatieren, Tests ausführen, linten
SessionStart	Eine Sitzung beginnt oder wird fortgesetzt	Branch-, Ticket- oder Umgebungskontext laden
Stop	Claude seine Antwort abschließt	„Tests müssen bestehen, bevor du stoppst“ erzwingen
SubagentStop	Ein Subagent abschließt	Die Ausgabe eines Subagenten validieren
Notification	Claude eine Benachrichtigung sendet	Desktop-Hinweise, wenn eine Eingabe benötigt wird

Die beiden, die du am häufigsten verwenden wirst, sind PreToolUse (um Dinge zu verhindern) und PostToolUse (um zu reagieren, nachdem sie passiert sind). Ein matcher-Feld lässt jeden Hook bestimmte Tools ansprechen, sodass ein Formatierer nur bei Edit und Write auslöst, während ein Befehls-Guard nur bei Bash auslöst.

So konfigurierst du deinen ersten Hook

Hooks leben in einem hooks-Block innerhalb einer Settings-Datei. Wo du diese Datei ablegst, entscheidet über ihren Geltungsbereich:

Datei	Geltungsbereich	Teilbar
~/.claude/settings.json	Jedes Projekt auf deinem Rechner	Nein
.claude/settings.json	Ein Projekt	Ja, committe sie ins Repo
.claude/settings.local.json	Ein Projekt, privat	Nein, per gitignore ausgeschlossen

Die Struktur verschachtelt drei Ebenen: das Event, eine matcher-Gruppe, die filtert, auf welche Tools es zutrifft, und den Handler, der die eigentliche Arbeit erledigt. Hier ist der Desktop-Benachrichtigungs-Hook aus Anthropics Einrichtungsanleitung, der dich benachrichtigt, sobald Claude auf dich wartet:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Waiting for your input'" }
        ]
      }
    ]
  }
}

Füge das zu .claude/settings.json hinzu, starte die Sitzung neu, und der Hook ist aktiv. Ein leerer Matcher bedeutet „passt auf alles“. Das ist das gesamte mentale Modell: Wähle ein Event, grenze es optional mit einem Matcher ein, richte es auf einen Befehl.

Ein funktionierendes Beispiel: Bearbeitungen formatieren und riskante Befehle blockieren

Zwei Hooks machen sich in fast jedem Projekt bezahlt. Der erste formatiert jede Datei, die Claude anfasst; der zweite weigert sich, destruktive Shell-Befehle auszuführen.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

Der PreToolUse-Guard ist ein kleines Skript, das den vorgeschlagenen Befehl liest und entscheidet, ob es ihn zulässt. Hier kommen Exit-Codes ins Spiel: Exit 0 bedeutet „kein Einwand, weiter geht's“, während Exit 2 ein blockierender Fehler ist, der das Tool stoppt und deine Nachricht an Claude zurückgibt. Für feinere Kontrolle kannst du auch strukturiertes JSON ausgeben:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qE 'rm -rf|:(){:|:&};:'; then
  jq -n '{ hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "Destructive command blocked by project hook"
  }}'
  exit 0
fi
exit 0

Jetzt kann Claude in diesem Projekt physisch kein rm -rf ausführen, und jede bearbeitete Datei kommt formatiert heraus, ohne dass eines der beiden Verhalten davon abhängt, dass das Modell daran denkt.

Prompt-basierte und agentenbasierte Hooks (neu in 2026)

Nicht jede Regel ist ein sauberes Ja/Nein, das du in einem Shell-Skript ausdrücken kannst. Anthropic hat 2026 zwei Hook-Typen für Entscheidungen ergänzt, die Urteilsvermögen erfordern. Ein Prompt-basierter Hook (type: "prompt") sendet die Eingabe des Hooks an ein Claude-Modell, standardmäßig Haiku, und lässt das Modell die Entscheidung zurückgeben, nützlich für etwas wie „blockiere diese Commit-Nachricht, wenn sie einen Kundennamen preisgibt“. Ein agentenbasierter Hook (type: "agent") startet einen Subagenten, um etwas Aufwändigeres zu überprüfen, bevor Claude fortfährt. Beide tauschen den Determinismus eines Shell-Befehls gegen Flexibilität, und beide kosten einen Modellaufruf, also behalte sie für die Fälle vor, die eine Regex wirklich nicht bewältigen kann. Für die überwiegende Mehrheit der Hooks ist ein einfacher command schneller, kostenlos und vollständig vorhersehbar.

Hooks vs. Skills, Subagenten und CLAUDE.md

Claude Code bietet dir mehrere Erweiterungspunkte, und der häufige Fehler ist, den falschen zu verwenden. Die Trennlinie ist der Determinismus.

• Hooks erzwingen eine Regel mit Code. Verwende sie, wenn etwas jedes Mal passieren muss, unabhängig davon, was das Modell entscheidet: Formatierung, Schutzmaßnahmen, Benachrichtigungen, Kontexteinspeisung.
• Skills geben Claude wiederverwendbare Anweisungen und Skripte, die es anwendet, wenn eine Situation passt. Sie erweitern Fähigkeiten, nicht Durchsetzung.
• Subagenten führen Arbeit in einem isolierten Kontext aus, damit eine große Aufgabe den Haupt-Thread nicht überflutet. Es geht um Kontext, nicht um Regeln.
• CLAUDE.md ist beständige Anleitung, die das Modell liest und meistens befolgt, aber überschreiben kann.

Wenn deine Anweisung immer wieder ignoriert wird, ist das das Signal, sie von einer CLAUDE.md-Zeile zu einem Hook hochzustufen. Hooks passen auch natürlich zu MCP-Servern: Ein Hook kann ein MCP-Tool aufrufen oder bei der Nutzung eines MCP-Tools auslösen, um Claude mit deinen bestehenden Systemen zu verdrahten.

Ist das sicher? Hooks laufen mit deinen vollen Berechtigungen

Ja, mit einem ernsten Vorbehalt: Hooks führen beliebige Befehle auf deinem Rechner mit den Berechtigungen deines Benutzers aus, automatisch und ohne Bestätigungsabfrage. Anthropics Anleitung sagt unumwunden, dass du allein dafür verantwortlich bist, was deine Hooks tun, und dass ein unachtsamer Hook Dateien löschen oder Daten beschädigen kann. Füge niemals eine Hook-Konfiguration aus einer nicht vertrauenswürdigen Quelle ein, ohne zuvor jeden Befehl zu lesen, halte gemeinsam genutzte Hooks in einer committeten .claude/settings.json, damit Teammitglieder sie überprüfen können, und bevorzuge blockierende Guards gegenüber allem, was von sich aus schreibt oder löscht. Behandle einen Hook so, wie du jedes Skript behandeln würdest, das unbeaufsichtigt läuft.

Häufig gestellte Fragen

Wofür kann man Claude Code Hooks verwenden?

Die häufigsten Verwendungen sind automatisches Formatieren und Linten nach Bearbeitungen, das Blockieren gefährlicher oder richtlinienwidriger Befehle, das Ausführen von Tests, bevor Claude einen Turn abschließt, das Senden von Desktop-Benachrichtigungen, wenn Claude eine Eingabe benötigt, und das Einspeisen von Kontext (Git-Branch, Ticketnummer, Umgebung) beim Sitzungsstart.

Was ist der Unterschied zwischen einem Hook und einer CLAUDE.md-Regel?

Eine CLAUDE.md-Regel ist Anleitung, die das Modell liest und meistens befolgt, aber ignorieren oder vergessen kann. Ein Hook wird durch Code erzwungen und läuft jedes Mal, wenn sein Event auslöst. Verwende CLAUDE.md für Präferenzen und Hooks für alles, was garantiert sein muss.

Wie viele Hook-Events gibt es, und wo ist die vollständige Liste?

Claude Code stellt mehr als dreißig Lebenszyklus-Events bereit, von SessionStart über PreToolUse, PostToolUse, Stop bis zu Subagenten-Events. Die vollständige, aktuelle Liste mit Eingabe- und Ausgabeschemata findet sich in der offiziellen Hooks-Referenz.

Verlangsamen Hooks Claude Code?

Command-Hooks sind in der Regel schnell und alle passenden Hooks laufen parallel, sodass der Mehraufwand gering ist. Prompt-basierte und agentenbasierte Hooks fügen einen Modellaufruf hinzu und sind langsamer, also reserviere sie für Entscheidungen, die ein Shell-Skript nicht treffen kann.

Quellen

• Claude Code Docs — Hooks-Referenz: offizielle Liste der Lebenszyklus-Events, Konfigurationsstruktur, Matcher, Eingabeschema, Exit-Codes und JSON-Ausgabefelder.
• Claude Code Docs — Aktionen mit Hooks automatisieren (Anleitung): Durchlauf des ersten Hooks, Prompt-basierte und agentenbasierte Hooks und die Sicherheitswarnung, dass Hooks mit deinen Berechtigungen laufen.