Hooks einrichten in Claude Code

Hooks sind Shell-Befehle, die Claude Code an festgelegten Lifecycle-Events automatisch ausführt – vor einem Tool-Aufruf, nach einem Tool-Aufruf, beim Session-Start oder am Turn-Ende. Sie sind deterministisch (kein LLM-Call, kein Token-Verbrauch) und greifen IMMER, unabhängig davon, ob Claude eine Regel im Kopf hat oder nicht.

Für wen ist das?

Für Entwickler, die professionelle Claude-Code-Setups bauen – mit Security-Gates, Compliance-Regeln oder Team-Standards. Wer eine Regel hat, die niemals umgangen werden darf, schreibt sie als Hook.

Was lernst du?

• Was Hooks sind und warum sie deterministisch wichtig sind
• Welche Lifecycle-Events es gibt und wann sie feuern
• Wie du PreToolUse als Security-Gate konfigurierst
• Wie du PostToolUse für Auto-Format und Audit-Logs nutzt
• Wie du Hooks asynchron und HTTP-basiert betreibst

Wann nutzen?

• Security-Gate: Bestimmte Dateien (.env, Migrations, Secrets) niemals editieren lassen
• Auto-Format: Nach jedem Edit automatisch prettier/black/gofmt laufen lassen
• Audit-Log: Jeden Bash-Befehl in eine Datei schreiben, damit du nachvollziehen kannst, was passiert ist
• Pflicht-Review: Bevor Claude pushen darf, lokalen Test-Lauf erzwingen
• Notifications: Am Session-Ende Slack-Message schicken, wenn etwas committet wurde

Wann nicht?

• Für kontextabhängige Verhaltensregeln (gehört in CLAUDE.md oder einen Skill)
• Für intelligente Entscheidungen, die ein LLM treffen muss (gehört in einen Subagent)
• Wenn der Befehl langsam ist und du Claude nicht ausbremsen willst (dann async oder gar nicht)

Die wichtigsten Lifecycle-Events

PreToolUse ist der einzige Hook, der eine Aktion blockieren kann: Exit-Code 2 stoppt den Tool-Call, Exit-Code 0 lässt ihn durch.

Hook konfigurieren

Hooks leben in .claude/settings.json – pro Event ein Eintrag mit Matcher-Regex und Hook-Liste:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/protect-secrets.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATHS",
            "async": true
          }
        ]
      }
    ]
  }
}

Der Matcher ist eine Regex auf den Tool-Namen – Edit|Write greift bei beiden, .* bei allem.

Security-Gate: PreToolUse zum Schutz von Secrets

Ein simples, mächtiges Pattern: niemals .env-Dateien oder Migrationen editieren lassen.

#!/bin/bash
# .claude/hooks/protect-secrets.sh

# Hook bekommt JSON via stdin
INPUT=$(cat)
PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if echo "$PATH" | grep -qE '\.env$|/migrations/|secrets\.yaml'; then
  echo "BLOCKED: $PATH ist geschützt" >&2
  exit 2  # Block
fi
exit 0  # Allow

Exit-Code 2 → Claude bekommt die Fehlermeldung und versucht den Edit nicht erneut.

Auto-Format mit PostToolUse

Nach jedem Edit den Formatter laufen lassen – ohne Claude zu bremsen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null",
            "async": true
          }
        ]
      }
    ]
  }
}

"async": true lässt den Befehl im Hintergrund laufen – Claude wartet nicht, du gewinnst Geschwindigkeit.

Hook anlegen – Schritt für Schritt

Typische Fehler

• Hook ohne Async: Ein synchroner npm run lint nach jedem Edit verlangsamt Claude spürbar. Setze async: true, wenn die Reaktion nicht blockend sein muss.
• Matcher zu weit: Ein Matcher .* auf PreToolUse betrifft auch Read-Operationen – das ist meist nicht gewollt. Sei spezifisch (Edit|Write|Bash).
• Exit-Code missverstanden: Exit-Code 2 ist nur bei PreToolUse Block-Signal. Bei PostToolUse ist es einfach ein Fehler ohne Block.
• Hook nicht ausführbar: chmod +x vergessen → Hook scheitert mit Permission Denied. Im Setup-Skript fest verdrahten.
• Hooks für intelligente Entscheidungen: Hooks sind dumm und deterministisch. Wenn du „Entscheide, ob diese Migration sicher ist” willst, brauchst du einen Subagent, keinen Hook.

Mini-Übung

Baue einen Audit-Log-Hook für Bash-Befehle:

1. Lege .claude/hooks/audit-bash.sh an
2. Inhalt: echo "$(date -Iseconds) $(echo $(cat) | jq -r '.tool_input.command')" >> .claude/audit.log
3. chmod +x .claude/hooks/audit-bash.sh
4. In .claude/settings.json als PostToolUse mit Matcher Bash registrieren, async: true
5. Claude ein paar Bash-Befehle ausführen lassen
6. cat .claude/audit.log – du siehst ein lückenloses Protokoll

Nächster Schritt

Du weißt jetzt, wie du Claude Codes Verhalten deterministisch steuerst. Als Nächstes: Wenn dein Setup wächst, lohnt sich der Guide Plugins und Marketplace – denn Plugins bündeln Skills, Hooks und MCP-Server zu wiederverwendbaren Paketen, die du installieren und teilen kannst.