Hook-Events & Handler

Wissen

Die wichtigsten Hook-Events

Claude Code feuert an 24 Stellen im Workflow Events. Jedes Event ist ein Eingriffspunkt, an dem du deterministisches Verhalten erzwingen kannst. Hier die wichtigsten:

Die 4 Handler-Typen

Jeder Hook braucht einen Handler -- die Logik, die beim Event ausgeführt wird:

1. Command-Handler (Standard)

Der häufigste Typ. Führt ein Shell-Script aus und empfängt den Event-Kontext als JSON über stdin.

{
  "type": "command",
  "command": "npx prettier --write $TOOL_INPUT_FILE_PATH"
}

Das Script erhält alle relevanten Informationen: welches Tool aufgerufen wurde, mit welchen Argumenten, und was das Ergebnis war. Perfekt für Linting, Tests, Formatierung und Sicherheitschecks.

2. HTTP-Handler

Sendet einen POST-Request an einen HTTP-Endpoint. Ideal für Logging, Webhooks oder die Integration mit externen Systemen.

{
  "type": "http",
  "url": "https://your-server.com/hooks/log",
  "headers": { "Authorization": "Bearer $TOKEN" }
}

3. Prompt-Handler

Nutzt ein leichtgewichtiges LLM (Haiku) für einen einzelnen Evaluations-Turn. Gut für Entscheidungen, die menschliches Urteil simulieren.

{
  "type": "prompt",
  "prompt": "Prüfe ob dieser Code-Änderung die bestehende API bricht. Antworte nur mit PASS oder FAIL."
}

4. Agent-Handler

Der mächtigste Typ: Ein Multi-Turn LLM mit Tool-Zugriff, der bis zu 50 Turns ausführen kann. Für komplexe Prüfungen wie "Hat diese Änderung alle Tests aktualisiert?"

{
  "type": "agent",
  "prompt": "Prüfe ob die geänderten Dateien entsprechende Test-Updates haben. Führe die Tests aus und berichte.",
  "maxTurns": 10
}

Exit-Codes: Die Sprache der Hooks

Hooks kommunizieren über Exit-Codes mit Claude Code:

Das ist elegant: Exit-Code 0 heißt "weitermachen", Exit-Code 2 heißt "stopp". Alles andere wird als nicht-kritischer Fehler behandelt und läuft weiter.

#!/bin/bash
# Beispiel: Blockiere force-push
if echo "$1" | grep -q "push.*--force"; then
  echo "Force-push ist nicht erlaubt!" >&2
  exit 2
fi
exit 0

Matcher und if-Filter

Nicht jeder Hook soll bei jedem Tool-Aufruf feuern. Dafür gibt es zwei Filtermechanismen:

Matcher: Regex auf den Tool-Namen

{
  "matcher": "Edit|Write",
  "hooks": [{ "type": "command", "command": "npx prettier --write" }]
}

Dieser Hook feuert nur bei Edit- und Write-Aufrufen, nicht bei Bash oder Read.

if-Filter: Tool + Argument

{
  "matcher": "Bash",
  "if": "Bash(git commit*)",
  "hooks": [{ "type": "command", "command": "npm test" }]
}

Der if-Filter ist mächtig: Er matcht nicht nur den Tool-Namen, sondern auch die Argumente. Bash(git commit*) feuert nur, wenn Claude einen git commit-Befehl ausführen will -- nicht bei jedem Bash-Aufruf.

Wo Hooks gespeichert werden

Hooks können an vier Orten definiert werden, mit aufsteigender Priorität:

1. Global (~/.claude/settings.json) -- Gilt für alle Projekte. Ideal für persönliche Präferenzen wie Formatierung oder Notifications.
2. Projekt (.claude/settings.json) -- Gilt für das gesamte Team. Wird ins Git-Repository committed.
3. Lokal (.claude/settings.local.json) -- Persönliche Projekt-Overrides. Wird NICHT committed (in .gitignore).
4. Skill/Agent Frontmatter -- Hooks innerhalb eines Skills oder Agent-Definitions. Gilt nur für diesen Skill.

Verstehen

Probiere den Hook-Event-Simulator aus: Wähle ein Szenario und beobachte, welche Events in welcher Reihenfolge feuern. Klicke auf einzelne Events, um Details und Beispiel-Konfigurationen zu sehen.

Anwenden

Überlege für dein aktuelles Projekt: Welche Aktionen sollen IMMER nach einer Dateiänderung laufen? Welche Befehle sollen NIEMALS ohne Prüfung ausgeführt werden? Die Antworten darauf zeigen dir, welche Events und Handler du brauchst. Im nächsten Abschnitt bekommst du fertige Rezepte zum Kopieren.