Claude Code Hooks: Der Power-User-Guide zur Automatisierung deines Agenten

Claude Code Hooks sind benutzerdefinierte Befehle, die automatisch an bestimmten Punkten im Lebenszyklus von Claude Code ausgeführt werden — vor einem Tool-Aufruf, nach einer Bearbeitung, wenn eine Sitzung beginnt, wenn Claude einen Zug abschließt —, sodass Sie Aktionen validieren, formatieren, protokollieren oder blockieren können, ohne jedes Mal selbst eingreifen zu müssen. Sie machen den Unterschied zwischen einem KI-Coding-Agenten, der vorschlägt, und einem, der Ihren Regeln deterministisch folgt. Dieser Leitfaden erklärt, was Hooks sind, jedes Ereignis, auf das sie reagieren können, wie man sie konfiguriert, fünf praktische Rezepte zum Nachbauen, die Exit-Code-Falle, in die jeder tappt, und wie Sie die volle Leistung von Claude Code ganz ohne lokale Einrichtung nutzen können.

Was sind Claude Code Hooks?

Ein Hook ist ein Handler – ein Shell-Befehl, ein HTTP-Endpunkt, ein MCP-Tool-Aufruf oder sogar ein Modell-Prompt –, den Claude Code automatisch ausführt, wenn ein bestimmtes Ereignis eintritt. Der Handler erhält strukturierte Eingaben (über stdin bei Command-Hooks oder als POST-Body bei HTTP-Hooks), kann prüfen, was gerade passiert, eine Aktion ausführen und optional eine Entscheidung zurückgeben, die verändert, was Claude als Nächstes tut.

Genau dieser letzte Punkt macht Hooks mächtig statt nur praktisch. Ein Hook ist nicht nur eine Benachrichtigung – er kann einen Tool-Aufruf blockieren, die Ein- oder Ausgabe eines Tools umschreiben, zusätzlichen Kontext einfügen oder Claude komplett stoppen. Mit anderen Worten: Hooks verwandeln Claude Code von einem cleveren Assistenten in ein programmierbares System, das die Leitplanken Ihres Teams deterministisch durchsetzt – nicht nur dann, wenn das Modell zufällig daran denkt.

Wann Hooks auslösen: Der Lebenszyklus

Hooks knüpfen an Ereignisse an, und Claude Code stellt davon eine ganze Menge bereit. Sie lassen sich nach Häufigkeit gruppieren: manche feuern einmal pro Sitzung, manche einmal pro Zug und manche bei jedem Tool-Aufruf.

Wo Hooks innerhalb einer Claude-Code-Sitzung auslösen – von SessionStart bis SessionEnd.

Die Ereignisse, die Sie am häufigsten nutzen werden:

• SessionStart / SessionEnd — einmal, wenn eine Sitzung beginnt oder endet. Ideal, um Kontext zu laden (offene Issues, Branch-Informationen, Umgebungsvariablen) oder aufzuräumen.
• UserPromptSubmit — löst aus, wenn Sie einen Prompt absenden, bevor Claude ihn verarbeitet. Sie können den Prompt filtern oder ergänzen.
• PreToolUse — vor jedem Tool-Aufruf. Hier blockieren Sie gefährliche Aktionen.
• PostToolUse (und PostToolUseFailure) — nach einem erfolgreichen (oder fehlgeschlagenen) Tool-Aufruf. Der richtige Ort für Linting, Formatierung und Verifikation.
• Stop / StopFailure — wenn Claude die Antwort abschließt oder der Zug mit einem Fehler endet.
• Notification — wenn Claude Code eine Benachrichtigung ausgibt (nützlich für Desktop-Alerts).

Darüber hinaus feuert Claude Code auch Hooks für Subagenten (SubagentStart/SubagentStop), Tasks (TaskCreated/TaskCompleted), Kontext-Kompaktierung (PreCompact/PostCompact), Änderungen des Arbeitsverzeichnisses (CwdChanged), Dateiänderungen auf der Festplatte (FileChanged), das Laden von Anweisungen (InstructionsLoaded) und mehr. Die Bandbreite ist der Punkt: An fast jedem Moment in der Schleife des Agenten können Sie Richtlinien anknüpfen.

Die fünf Arten von Hook-Handlern

Ein Hook-Ereignis kann fünf verschiedene Arten von Handlern auslösen, was das System flexibel macht:

1. command — führt einen Shell-Befehl aus; liest die Eingabe über stdin, signalisiert Entscheidungen über Exit-Code und stdout.
2. http — sendet das Ereignis als JSON per POST an eine URL und liest die JSON-Antwort.
3. mcp_tool — ruft ein Tool auf einem verbundenen MCP-Server auf.
4. prompt — eine einmalige Modellauswertung, die eine Ja/Nein-Entscheidung als JSON zurückgibt (nützlich für unscharfe Prüfungen).
5. agent — startet einen Subagenten (experimentell).

Für die meisten Teams erledigen command-Hooks 90 % der Arbeit — ein Shell-Skript reicht aus, um zu linten, zu blockieren oder zu protokollieren.

Wie man einen Hook konfiguriert

Hooks liegen in Settings-Dateien (die offizielle Claude-Code-Hooks-Dokumentation ist die maßgebliche Referenz), und wo Sie sie platzieren, bestimmt ihren Geltungsbereich:

Die Struktur verschachtelt drei Ebenen: Wählen Sie ein Ereignis, fügen Sie eine Matcher-Gruppe hinzu und definieren Sie dann die Handler. Matcher entscheiden, auf welche Tool-Aufrufe ein Hook angewendet wird — "*" (oder das Weglassen) passt auf alles, ein einfaches Edit|Write passt auf genau diese Tools, und alles Komplexere wird als regulärer Ausdruck behandelt. (MCP-Tools entsprechen dem Muster mcp__<server>__<tool>.)

Hier ist ein PostToolUse-Hook, der nach jeder Bearbeitung eine Lint-Prüfung ausführt:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Fünf praktische Hook-Rezepte

Das sind die Muster, zu denen Teams zuerst greifen:

1. Nach jeder Bearbeitung linten oder formatieren. Ein PostToolUse-Hook, gematcht auf Edit|Write, der Ihren Formatter oder Linter ausführt, sodass der Code des Agenten immer Ihren Stilregeln entspricht.
2. Destruktive Befehle blockieren. Ein PreToolUse-Hook, gematcht auf Bash, der den Befehl prüft und rm -rf und Ähnliches blockiert, bevor es überhaupt ausgeführt wird.
3. Desktop-Benachrichtigungen. Ein Notification-Hook, der Sie benachrichtigt, wenn Claude Ihre Aufmerksamkeit braucht oder eine lange Aufgabe abschließt.
4. Audit-Protokollierung. Ein PostToolUse- (oder MCP-gezielter) Hook, der jeden Tool-Aufruf zu Compliance-Zwecken protokolliert — was ausgeführt wurde, wann und mit welchen Argumenten.
5. Projektkontext beim Start laden. Ein SessionStart-Hook, der offene Issues, den aktuellen Branch oder Umgebungsvariablen lädt, sodass der Agent jede Sitzung bereits orientiert beginnt.

Fünf gängige Hook-Rezepte und die Ereignisse, an die sie anknüpfen.

Die Exit-Code-Falle

Das ist das Detail, in das jeder tappt, also prägen Sie sich das ein: Bei command-Hooks blockiert nur Exit-Code 2. Exit 0 bedeutet Erfolg (und stdout wird auf eine mögliche JSON-Entscheidung geparst). Exit 2 ist ein blockierender Fehler — sein stderr wird an Claude zurückgemeldet. Jeder andere Code, einschließlich Exit 1, ist ein nicht-blockierender Fehler — Claude macht weiter.

Wenn Sie also einen "das hier blockieren"-Hook schreiben und exit 1 verwenden, wird er nicht blockieren — die Aktion wird fortgesetzt. Um eine Richtlinie aus einem Command-Hook tatsächlich durchzusetzen, verwenden Sie exit 2. (Command-Hooks können auch umfangreichere Steuerung als JSON auf stdout zurückgeben — permissionDecision: "deny" für PreToolUse, updatedInput, um Argumente umzuschreiben, additionalContext, um Informationen einzufügen, und continue: false, um Claude vollständig zu stoppen.)

Ein durchgearbeitetes Beispiel: rm -rf blockieren

Bauen wir die Schutzvorrichtung gegen destruktive Befehle von Anfang bis Ende, denn sie zeigt jedes bewegliche Teil. Zuerst die Konfiguration — ein PreToolUse-Hook, gematcht auf Bash:

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Dann das Skript, guard.sh. Claude Code sendet das Ereignis als JSON über stdin, einschließlich der Tool-Eingabe; das Skript liest es ein, prüft den Befehl und entscheidet:

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

Die entscheidende Zeile ist exit 2. Geben Sie 0 zurück, wird der Befehl ausgeführt; geben Sie 1 zurück, wird er — kontraintuitiverweise — trotzdem als nicht-blockierender Fehler ausgeführt; nur exit 2 blockiert und speist Ihre stderr-Meldung zurück an Claude, damit es versteht, warum. Machen Sie das Skript ausführbar, committen Sie es unter .claude/hooks/, und schon läuft jeder Bash-Aufruf durch Ihre Schutzvorrichtung — für Ihr gesamtes Team, da die projektweite settings.json teilbar ist. Für eine harte Garantie statt eines Best-Effort-Netzes kombinieren Sie es mit den Berechtigungsregeln von Claude Code; als deterministisches, versioniertes Sicherheitsnetz erfüllt dieser Hook aber bereits seinen Zweck.

Wann Hooks nicht die Antwort sind

Hooks eignen sich für deterministische, wiederholbare Richtlinien — "nach einer Bearbeitung immer linten", "niemals rm -rf ausführen". Sie sind das falsche Werkzeug für Dinge, die Urteilsvermögen erfordern (nutzen Sie dafür das Modell oder einen prompt-Hook für unscharfe Entscheidungen) und für harte Sicherheitsgarantien (nutzen Sie das Berechtigungssystem, da if-Filter bei Command-Hooks im Zweifel durchlassen). Übertreiben Sie es auch nicht mit Hooks: Jeder Command-Hook führt einen Prozess mit Timeout aus, und ein Dickicht aus langsamen Hooks fügt jedem Tool-Aufruf Latenz hinzu. Halten Sie sie schnell, wenige an der Zahl und fokussiert auf die Regeln, die wirklich zählen.

Sicherheitshinweise, die Sie kennen sollten

Ein paar Realitäten, die die Dokumentation ausdrücklich benennt:

• Der if-Filter lässt im Zweifel durch (fail open). Wenn Sie das if-Feld verwenden, um einen Hook auf eine Berechtigungsregel einzugrenzen, und der Befehl nicht geparst werden kann, wird der Hook trotzdem ausgeführt. Für eine harte Erlauben/Verbieten-Durchsetzung nutzen Sie Claude Codes Berechtigungssystem, nicht Hooks.
• Hooks laufen ohne steuerndes Terminal — sie können nicht über /dev/tty nachfragen. Verwenden Sie systemMessage oder die eingeschränkte terminalSequence-Ausgabe für nutzerseitige Meldungen.
• Stdout muss sauber sein. Nur das JSON-Entscheidungsobjekt sollte auf stdout stehen; verstreute Ausgaben aus Shell-Profilen können das Parsing brechen.
• Behandeln Sie eingefügten Kontext mit Vorsicht. additionalContext sollte als sachliche Aussage formuliert werden, nicht als Befehl, um sich gut mit Prompt-Injection-Abwehrmaßnahmen zu vertragen.

Hooks sind Harness Engineering im Kleinen

Tritt man einen Schritt zurück, sind Hooks ein konkretes Beispiel für eine größere Idee: Das Modell ist nicht der ganze Agent — das System drumherum ist es auch. Hooks sind Teil des Harness, das einen Coding-Agenten zuverlässig macht, neben Loop, Tools, Memory und Sandbox. (Wir gehen in Harness Engineering ausführlich auf dieses mentale Modell ein.) Wenn Sie einen PreToolUse-Block oder einen PostToolUse-Linter schreiben, betreiben Sie Harness Engineering — Sie formen das Verhalten des Agenten deterministisch, statt darauf zu hoffen, dass sich das Modell richtig verhält.

Dieser Blickwinkel verrät auch, wann sich Hooks lohnen: Jede Regel, an die Sie den Agenten sonst jedes Mal aufs Neue erinnern müssten, ist ein Kandidat für einen Hook.

Die volle Leistung von Claude Code ohne lokale Einrichtung nutzen

Hooks leben in der Claude-Code-CLI, was bedeutet, dass Sie sie installiert und konfiguriert brauchen, um sie zu nutzen — eine Hürde für jeden, der nicht im Terminal zuhause ist, und unmöglich für Teammitglieder ohne Entwicklerhintergrund. Wenn Sie die Agentenfähigkeiten von Claude Code ohne die Verwaltung einer lokalen Installation nutzen möchten, können Sie Claude Code in Ihrem Browser ausführen auf Happycapy: Es führt Claude Code in einer verwalteten Cloud-Sandbox aus, in der der Harness — die Schleife, die Tools, das Memory und die Isolierung, an die Hooks andocken — bereits für Sie eingerichtet ist. Sie beschreiben eine Aufgabe und beobachten den Agenten bei der Arbeit auf einem visuellen Desktop, ganz ohne Terminal.

Man kann es sich so vorstellen: Hooks lassen fortgeschrittene Nutzer den Harness von Claude Code von Hand feinjustieren; Happycapy gibt jedem von Anfang an einen verwalteten Harness. Wenn Sie Claude Code schon länger einsetzen wollten, aber die CLI-Einrichtung Sie aufgehalten hat, starten Sie kostenlos auf happycapy.ai und führen Sie noch heute eine echte Aufgabe in Ihrem Browser aus.

Häufig gestellte Fragen

F: Was sind Claude Code Hooks?

Es sind benutzerdefinierte Handler — Shell-Befehle, HTTP-Endpunkte, MCP-Tool-Aufrufe oder Modell-Prompts —, die Claude Code automatisch bei Lebenszyklus-Ereignissen ausführt, etwa vor einem Tool-Aufruf (PreToolUse), nach einer Bearbeitung (PostToolUse) oder beim Sitzungsstart. Sie können Aktionen validieren, formatieren, protokollieren, blockieren oder umschreiben.

F: Welche Hook-Ereignisse unterstützt Claude Code?

Viele — darunter SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (und PostToolUseFailure), Stop/StopFailure, Notification sowie Subagenten- und Task-Ereignisse und Kompaktierungs-Ereignisse. Sie feuern einmal pro Sitzung, einmal pro Zug oder bei jedem Tool-Aufruf.

F: Wie bringe ich einen Hook dazu, einen Tool-Aufruf zu blockieren?

Bei Command-Hooks beenden Sie den Prozess mit Code 2 — nur Exit 2 blockiert (Exit 1 nicht). Für PreToolUse können Sie außerdem JSON mit permissionDecision: "deny" zurückgeben. Für eine harte Durchsetzung bevorzugen Sie das Berechtigungssystem von Claude Code, da der if-Filter des Hooks im Zweifel durchlässt.

F: Wo konfiguriere ich Claude Code Hooks?

In Settings-Dateien: ~/.claude/settings.json (alle Projekte), .claude/settings.json (ein Projekt, teilbar) oder .claude/settings.local.json (nur lokal). Sie wählen ein Ereignis, fügen einen Matcher hinzu und definieren Handler.

F: Kann ich Claude Code Hooks nutzen, ohne die CLI zu installieren?

Hooks selbst erfordern die Claude-Code-CLI. Wenn Ihr Ziel ist, Claude Code ohne lokale Einrichtung zu nutzen, führen Sie es in einer verwalteten Browser-Sandbox wie Happycapy aus, die den Agenten und seinen Harness einsatzbereit bereitstellt — ideal, wenn Sie die CLI nicht selbst installieren und konfigurieren möchten.

F: Was ist ein guter erster Hook zum Hinzufügen?

Ein PostToolUse-Linter, gematcht auf Edit|Write — er führt Ihren Formatter nach jeder Codeänderung aus, sodass die Ausgabe des Agenten stets Ihren Stilregeln entspricht. Risikoarm und sofort nützlich.

Verwandte Leitfäden

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?