Hooks-Leitfaden

Problem: Du genehmigst jeden Dateischreibvorgang von Hand. Dann jeden Befehl. Dann jeden Format-Durchlauf. Zwanzig Unterbrechungen später ist das Feature, das du gerade gebaut hast, aus deinem Kopf verschwunden.

Quick Win: Füge das zu .claude/settings.json hinzu und genehmige nie wieder einen Prettier-Format-Durchlauf:

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

Jede Datei, die Claude schreibt, wird jetzt automatisch formatiert. Null Klicks. Null Kontextwechsel.

Die 12 Hook-Lifecycle-Events

Jedes Claude Code-Event kann einen Hook auslösen. Ein Hook führt einen Shell-Befehl aus oder sendet einen LLM-Prompt, wenn dieses Event feuert. Die vollständige Liste:

*Ein PostToolUse-Hook kann eine Nachricht an Claude zurückgeben, aber er kann das Tool, das bereits gelaufen ist, nicht rückgängig machen.

Exit-Codes: Der Kontrollmechanismus

Exit-Codes sind die Art, wie ein Hook mit Claude kommuniziert:

Exit-Code 2 ist der, der Dinge blockiert. Gib ihn von einem PreToolUse-Hook zurück und das Tool läuft nie. Gib ihn von einem Stop-Hook zurück und Claude muss weitermachen, statt fertig zu werden.

Hook-Typen: Command, HTTP, Prompt und Agent

Es gibt vier Handler-Typen. Nimm den, der zum Job passt.

Command-Hooks führen Shell-Skripte aus:

{
  "type": "command",
  "command": "python validator.py",
  "timeout": 30
}

HTTP-Hooks senden POST-Anfragen an einen Endpunkt und empfangen JSON zurück: Neu - Feb 2026

{
  "type": "http",
  "url": "http://localhost:8080/hooks/pre-tool-use",
  "timeout": 30,
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

Claude Code sendet das Event-JSON als Request-Body (Content-Type: application/json), und die Antwort folgt demselben JSON-Ausgabe-Schema, das ein Command-Hook verwenden würde. Ein paar Dinge unterscheiden sich:

• Nicht-blockierende Fehler: Eine Nicht-2xx-Antwort, ein Verbindungsfehler oder ein Timeout stoppen die Ausführung nicht. Um einen Tool-Call tatsächlich zu blockieren, musst du eine 2xx-Antwort mit decision: "block" im JSON-Body zurückgeben.
• Header-Env-Vars: Referenziere Variablen mit $VAR_NAME oder ${VAR_NAME} in Header-Werten. Nur Namen, die in allowedEnvVars aufgeführt sind, werden aufgelöst. Alles andere wird zu einem leeren String.
• Deduplizierung: HTTP-Hooks deduplizieren nach URL. Command-Hooks deduplizieren nach Befehlsstring.
• Nur Config: Du musst die Settings-JSON direkt bearbeiten. Das interaktive /hooks-Menü unterstützt nur Command-Hooks.

Prompt-Hooks nutzen LLM-Auswertung (eine gute Option für Stop und SubagentStop):

{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks complete.",
  "timeout": 30
}

Das LLM antwortet mit {"ok": true} oder {"ok": false, "reason": "..."}.

Agent-Hooks starten einen Subagenten, der Dateien lesen kann (Read, Grep, Glob) für eine tiefergehende Prüfung:

{
  "type": "agent",
  "prompt": "Verify all test files have corresponding implementation files",
  "timeout": 60
}

Ein Agent-Hook schaut sich erst im Codebase um und entscheidet dann. Das macht ihn gründlicher als einen Prompt-Hook. Er ist auch langsamer (Standard-Timeout: 60s versus 30s für Prompts).

Async-Hooks (Nicht-blockierend) Neu - Jan 2026

Setze async: true und der Hook läuft im Hintergrund, anstatt Claude zu blockieren. Anthropic hat das im Januar 2026 geliefert:

{
  "type": "command",
  "command": "node backup-script.js",
  "async": true,
  "timeout": 30
}

Am besten für:

• Logging und Analytics
• Backup-Erstellung (PreCompact)
• Benachrichtigungen
• Jeder Nebeneffekt, der die Arbeit nicht verlangsamen soll

Nicht geeignet für:

• Sicherheits-Blocking (PreToolUse mit Exit-Code 2)
• Auto-Approve-Entscheidungen (PermissionRequest)
• Jeden Hook, bei dem Claude das Ergebnis braucht

HTTP-Hooks: An Endpunkte senden Neu - Feb 2026

Richte einen HTTP-Hook auf eine Web-URL, die du besitzt, und das Event fließt dorthin anstatt in ein lokales Skript. Das öffnet eine Reihe von Patterns, die Command-Hooks nicht sauber handhaben konnten:

• Remote-Validierungsdienste, die teamweite Richtlinien durchsetzen
• Zentralisiertes Logging in ein gemeinsames Audit-System
• Webhook-Integrationen mit Slack, PagerDuty oder eigenen Dashboards
• Microservice-Architekturen, bei denen Hook-Logik neben deiner API läuft

Einfacher HTTP-Hook

Leite alle Bash-Befehle durch einen Validierungsendpunkt:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Was auf deinem Server ankommt, ist genau der stdin-Payload, den ein Command-Hook lesen würde, geliefert über den POST-Body. Antworte im JSON-Ausgabeformat und Claude Code parst es genauso.

HTTP-Antwortverarbeitung

HTTP-Hooks lesen Antworten anders. Keine Exit-Codes. Nur HTTP-Status und Antwort-Body:

Das Wichtige: Ein HTTP-Hook kann nicht über Status-Codes allein blockieren. Sende ein 4xx oder 5xx zurück und du bekommst einen protokollierten Fehler, während die Ausführung weiterläuft. Echtes Blockieren oder eine echte Berechtigungsablehnung braucht eine 2xx-Antwort, deren JSON-Body die Decision-Felder enthält:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by security policy"
  }
}

Sichere Header-Authentifizierung

Das headers-Feld kann Umgebungsvariablen interpolieren, aber nur wenn die Variable in allowedEnvVars erscheint. Das verhindert, dass Geheimnisse versehentlich durchsickern:

{
  "type": "http",
  "url": "https://hooks.example.com/validate",
  "headers": {
    "Authorization": "Bearer $API_KEY",
    "X-Team-Id": "$TEAM_ID"
  },
  "allowedEnvVars": ["API_KEY", "TEAM_ID"]
}

Ein $VAR, das nicht auf der Allowlist steht, wird still zu einem leeren String. Keine Warnung. Kein Fehler. Einfach leer. Überprüfe die Allowlist zweimal, bevor du es veröffentlichst.

JSON-Ausgabe: Erweiterte Steuerung

Wenn ein Exit-Code zu grob ist, kann ein Hook stattdessen eine strukturierte JSON-Antwort zurückgeben.

PreToolUse-Entscheidungen

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Safe read operation",
    "updatedInput": { "command": "modified-command" },
    "additionalContext": "Context for Claude"
  }
}

• "allow": Umgeht das Berechtigungssystem
• "deny": Blockiert das Tool, sagt Claude warum
• "ask": Fordert den Nutzer zur Bestätigung auf
• updatedInput: Tool-Parameter vor der Ausführung ändern

PermissionRequest-Entscheidungen

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": { "command": "npm run lint" }
    }
  }
}

Stop/SubagentStop-Durchsetzung

{
  "decision": "block",
  "reason": "Tests failing. Fix them before completing."
}

Hook 1: Auto-Format beim Speichern

Formatter nach jedem Dateischreibvorgang ausführen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          },
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Beide Hooks laufen parallel. Format und Lint sind beide fertig, bevor Claudes Antwort erscheint.

Hook 2: Session-Kontext-Injektion

Kontext beim Session-Start laden:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '## Git Status' && git status --short && echo '## TODOs' && grep -r 'TODO:' src/ | head -5"
          }
        ]
      }
    ]
  }
}

Umgebungsvariablen persistieren

Ein SessionStart- oder Setup-Hook kann Umgebungsvariablen definieren, die für die gesamte Session gelten:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-key' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Hook 3: Sicherheits-Blocking

Gefährliche Operationen mit PreToolUse stoppen:

#!/usr/bin/env python3
import json
import sys
import re
 
DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]
 
input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: Dangerous pattern", file=sys.stderr)
            sys.exit(2)
 
sys.exit(0)

Hook 4: Sichere Befehle Auto-Approve

Nutze PermissionRequest, um die Nachfrage zu überspringen, wenn ein Befehl bekanntermaßen sicher ist:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/auto-approve.py"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
import json
import sys
 
SAFE_PREFIXES = ['npm test', 'npm run lint', 'git status', 'ls']
 
input_data = json.load(sys.stdin)
command = input_data.get('tool_input', {}).get('command', '')
 
for prefix in SAFE_PREFIXES:
    if command.startswith(prefix):
        output = {
            "hookSpecificOutput": {
                "hookEventName": "PermissionRequest",
                "decision": {"behavior": "allow"}
            }
        }
        print(json.dumps(output))
        sys.exit(0)
 
sys.exit(0)  # Normal flow for other commands

Hook 5: Transkript-Backup

PreCompact ist der Moment, um ein Transkript zu sichern. Markiere den Hook als async: true, da ein Backup Claude nie blockieren muss:

{
  "hooks": {
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/backup-transcript.py",
            "async": true
          }
        ]
      }
    ]
  }
}

Die Matcher manual und auto trennen /compact von automatischer Komprimierung.

Hook 6: Task-Abschluss-Durchsetzung

Ein Stop-Hook verhindert, dass Claude einen Job zu früh als erledigt erklärt:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete: $ARGUMENTS. Return {\"ok\": false, \"reason\": \"...\"} if work remains."
          }
        ]
      }
    ]
  }
}

Der Stop-Hook-Leitfaden behandelt befehlsbasierte Versionen dieses Patterns.

Hook 7: Skill-Aktivierung

Ein Skill-Aktivierungs-Hook greift in den Prompt ein, bevor Claude ihn sieht, und hängt Skill-Empfehlungen an das Ende. Jedes Keyword, das du tippst, wird gegen einen Regelsatz geprüft, sodass der Postgres-Tuning-Skill in den Kontext gelangt, sobald du eine langsame Abfrage erwähnst. Einundzwanzig Skill-Kategorien nutzen dieses Pattern bereits innerhalb des SkillActivationHook des Code Kits:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/SkillActivationHook/skill-activation-prompt.mjs"
          }
        ]
      }
    ]
  }
}

Hook 8: Schwellenwert-basierte Backups via StatusLine

StatusLine ist der einzige Ort, wo du Live-Kontext-Metriken bekommst. Das macht es zum richtigen Ort, um ein Backup zu starten, wenn du einen Schwellenwert erreichst:

{
  "statusLine": {
    "type": "command",
    "command": "node .claude/hooks/ContextRecoveryHook/statusline-monitor.mjs"
  }
}

Wichtig: Das remaining_percentage-Feld hat bereits einen festen 33K-Token-Autocompact-Buffer einberechnet. Um die echte "frei bis Autocompact"-Zahl zu bekommen, rechne selbst:

const AUTOCOMPACT_BUFFER_TOKENS = 33000;
const autocompactBufferPct = (AUTOCOMPACT_BUFFER_TOKENS / windowSize) * 100;
const freeUntilCompact = Math.max(0, pctRemainTotal - autocompactBufferPct);

Zwei Trigger-Systeme laufen nebeneinander im Backup-Skript. Tokens sind der primäre Trigger. Prozentangaben liegen darunter als Sicherheitsnetz:

// Token-based triggers (primary - works across all window sizes)
const TOKEN_FIRST_BACKUP = 50000; // First backup at 50k tokens used
const TOKEN_UPDATE_INTERVAL = 10000; // Update every 10k tokens after
 
if (currentTotalTokens >= TOKEN_FIRST_BACKUP) {
  if (lastBackupTokens < TOKEN_FIRST_BACKUP) {
    runBackup(
      sessionId,
      `tokens_${Math.round(currentTotalTokens / 1000)}k_first`,
    );
  } else if (currentTotalTokens - lastBackupTokens >= TOKEN_UPDATE_INTERVAL) {
    runBackup(
      sessionId,
      `tokens_${Math.round(currentTotalTokens / 1000)}k_update`,
    );
  }
}
 
// Percentage-based triggers (safety net, especially for 200k windows)
const THRESHOLDS = [30, 15, 5];
for (const threshold of THRESHOLDS) {
  if (state.lastFree > threshold && freeUntilCompact <= threshold) {
    runBackup(sessionId, `crossed_${threshold}pct`);
  }
}
if (freeUntilCompact < 5 && freeUntilCompact < state.lastFree) {
  runBackup(sessionId, "continuous");
}

PreCompact feuert nur im Moment der Komprimierung. StatusLine-basierte Backups sichern die Session im Voraus, solange noch nichts kaputt ist. Der Token-Trigger ist am wichtigsten bei großen Fenstern wie 1M, wo ein Prozent-Trigger viel zu spät ankäme.

Architektur: Drei-Datei-Struktur

Das Backup-System teilt sich in drei Dateien mit getrennten Aufgaben:

.claude/hooks/ContextRecoveryHook/
├── backup-core.mjs        # Shared backup logic (parsing, formatting, saving)
├── statusline-monitor.mjs # Threshold detection + display (calls backup-core)
└── conv-backup.mjs        # PreCompact trigger (calls backup-core)

Eine Datei besitzt die eigentliche Backup-Arbeit. Passe an, wie Markdown gerendert wird, wie Dateien benannt werden oder wie der Status gespeichert wird, und beide Aufrufer erben die Änderung kostenlos.

Backup-Datei-Benennung

Backups verwenden nummerierte Dateinamen mit Zeitstempeln, damit die Historie leicht zu scannen ist:

.claude/backups/1-backup-26th-Jan-2026-4-30pm.md
.claude/backups/2-backup-26th-Jan-2026-5-15pm.md
.claude/backups/3-backup-26th-Jan-2026-5-45pm.md

StatusLine-Anzeige

Wenn ein Backup für die aktuelle Session existiert, zeigt die Statusline seinen Pfad direkt an:

[!] 25.0% free (50.0K/200K)
-> .claude/backups/3-backup-26th-Jan-2026-5-45pm.md

Du siehst auf einen Blick, welche Datei nach der Komprimierung wieder eingelesen werden soll.

Status-Tracking

Beide Hooks teilen eine Status-Datei unter ~/.claude/claudefast-statusline-state.json:

{
  "sessionId": "abc123",
  "lastFreeUntilCompact": 25.5,
  "currentBackupPath": ".claude/backups/3-backup-26th-Jan-2026-5-45pm.md"
}

Empfohlener Workflow: Sobald die Komprimierung auslöst, drücke /clear für einen sauberen Start und lade den Backup-Pfad, den die Statusline angezeigt hat. Sonst treten die automatisch generierte Zusammenfassung und deine wiederhergestellten Notizen auf die Füße.

Hook 9: Setup-Hooks für Installation und Wartung

Ein Setup-Hook läuft bevor deine Session startet, ausgelöst durch spezielle CLI-Flags:

claude --init           # Triggers Setup hook with matcher "init"
claude --init-only      # Same as above, but exits after hook (CI-friendly)
claude --maintenance    # Triggers Setup hook with matcher "maintenance"

Verbinde sie mit Matchern in settings.json:

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.py",
            "timeout": 120
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Flags mit Prompts kombinieren: Hänge einen Prompt direkt an das Flag.

claude --init "/install"

Der Hook läuft zuerst, deterministisch. Dann feuert der /install-Befehl, agentisch. Eine Aufruf, zwei Ausführungsmodi: ein geskriptetes Setup gefolgt von einem Agenten, der darüber nachdenkt.

Der Setup-Hooks-Leitfaden geht das gesamte Pattern von Anfang bis Ende durch, einschließlich Justfile-Setups und interaktiver Onboarding-Flows.

Konfigurationsorte

Hooks deaktivieren und einschränken

Alle Hooks deaktivieren

Wenn ein Hook Probleme verursacht oder du einfach eine saubere Basis willst, setze disableAllHooks auf true in deinen Settings:

{
  "disableAllHooks": true
}

Jeder Hook auf jedem Scope wird stumm. Nutzer, Projekt, lokal. Greif darauf zurück, wenn du einen außer Kontrolle geratenen Hook debuggst oder eine bekanntermaßen saubere Basis brauchst.

Managed-Hook-Einschränkungen

Organisationen, die zentralisierte Kontrolle brauchen, können allowManagedHooksOnly auf true in den Managed Settings setzen:

{
  "allowManagedHooksOnly": true
}

Schalte es ein und die einzigen Hooks, die Claude Code ausführt, sind die in den Managed Settings deklarierten plus SDK-Hooks. Nutzer-Scope, Projekt-Scope, Plugin-Scope: alle drei werden ignoriert. Kein lokaler Hook kann die Sicherheitshaltung der Organisation mehr umgehen.

Kombiniere diese Einstellung mit allowManagedPermissionRulesOnly, das Berechtigungsregeln auf dieselbe Weise einschränkt. Zusammen geben sie Admins die Kontrolle über die gesamte Oberfläche: die Berechtigungen selbst, plus jeden Hook, der sie erweitert.

Matcher-Syntax

Wichtig: Kein Leerzeichen um das |. Und Matcher-Strings unterscheiden zwischen Groß- und Kleinschreibung.

Event-spezifische Matcher

SessionStart: startup, resume, clear, compactPreCompact: manual, autoSetup: init, maintenanceNotification: permission_prompt, idle_prompt, auth_success

Umgebungsvariablen

Debugging

Hook wird nicht ausgelöst?

• Matcher-Syntax prüfen (Groß-/Kleinschreibung, keine Leerzeichen)
• Settings-Dateiort überprüfen
• Test: echo '{"session_id":"test"}' | python your-hook.py

Befehl schlägt fehl?

• Logging hinzufügen: command 2>&1 | tee ~/.claude/hook-debug.log
• Mit Debug ausführen: claude --debug
• Hooks brechen auf anderen Betriebssystemen? Schau dir die Cross-Platform-Hook-Patterns an

Endlosschleifen mit Stop?

• Überprüfe immer zuerst das stop_hook_active-Flag

Fang mit einem Hook an

Wähle den Reibungspunkt, der am meisten schmerzt:

• Jede Datei von Hand formatieren? PostToolUse-Formatter
• Den ganzen Tag sichere Befehle genehmigen? PermissionRequest-Auto-Approve
• Session öffnet ohne Kontext? SessionStart-Injektion
• Fortschritt durch Komprimierung verlieren? PreCompact-Backup
• Tasks werden zu früh als erledigt erklärt? Stop-Durchsetzung

Ein Hook. Ein Reibungspunkt weg. Dann iterieren. Wenn du das Setup überspringen willst, kommt das Code Kit mit 5 bereits konfigurierten Hooks: Skill-Aktivierung, Auto-Formatierung, Context Recovery, Permission-Automatisierung und Code-Validierung. Jeder einzelne basiert auf den obigen Patterns.