Claude Code Hooks 2026: Automatisierung auf Systemebene

Was sind Hooks?

Hooks sind Shell-Befehle, die Claude Code automatisch zu bestimmten Zeitpunkten ausführt — unabhängig davon, was Claude gerade macht. Sie laufen im Hintergrund und können:

• Jeden Bash-Befehl vor der Ausführung loggen oder blockieren
• Nach jeder Dateiänderung automatisch linting starten
• Am Session-Ende einen Git-Commit erstellen
• Bei jedem Tool-Aufruf Metriken sammeln

Hooks sind seit Anfang 2026 offiziell dokumentiert und in allen Claude Code Versionen ab 1.x verfügbar. In Deutschland sind sie kaum bekannt — die meisten Nutzer kennen nur CLAUDE.md und Tool-Konfiguration.

Die vier Hook-Typen

Hooks konfigurieren

Hooks werden in der settings.json konfiguriert. Je nach Scope gibt es drei Speicherorte:

# 1. Global (gilt für alle Projekte)
~/.claude/settings.json

# 2. Projekt-lokal (gilt nur im aktuellen Projekt)
.claude/settings.json

# 3. Projekt-lokal, nicht in Git (sensitive Hooks)
.claude/settings.local.json

Die Grundstruktur einer Hook-Konfiguration:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Claude führt Bash aus: $CLAUDE_TOOL_INPUT\" >> /tmp/bash.log"
          }
        ]
      }
    ]
  }
}

Das matcher-Feld akzeptiert Tool-Namen ("Bash", "Edit", "Write") oder "*" für alle Tools. Der Befehl bekommt Umgebungsvariablen mit Kontext:

7 praktische Hook-Beispiele

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo \"[$(date -u +%H:%M:%S)] BASH: $CLAUDE_TOOL_INPUT\" >> /logs/agent.log"
      }]
    }]
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "cd $CLAUDE_CWD && npx eslint --fix $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path') 2>&1 || true"
      }]
    }]
  }
}

# hook-guard.sh
#!/bin/bash
CMD=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command // ""')

# rm -rf auf wichtige Verzeichnisse verhindern
if echo "$CMD" | grep -qE "rm -rf.*(home|root|var|etc)"; then
  echo "BLOCKED: Gefährlicher rm-Befehl verweigert" >&2
  exit 2
fi

# git push --force auf main/master verhindern
if echo "$CMD" | grep -qE "git push.+--force.+(main|master)"; then
  echo "BLOCKED: Force-Push auf main/master verboten" >&2
  exit 2
fi

exit 0

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash /home/user/hooks/hook-guard.sh"
      }]
    }]
  }
}

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "cd $CLAUDE_CWD && git add -A && git diff --staged --quiet || git commit -m '[auto] Claude Session $(date +%Y-%m-%d-%H%M)'"
      }]
    }]
  }
}

# test-runner-hook.sh
#!/bin/bash
FILE=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path // ""')

# Nur für Python-Dateien
if [[ "$FILE" == *.py ]]; then
  cd $CLAUDE_CWD
  python -m pytest tests/ -x -q --tb=short 2>&1 | tail -20
fi

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "bash /home/user/hooks/test-runner-hook.sh"
      }]
    }]
  }
}

# telegram-notify.sh
#!/bin/bash
BOT_TOKEN="$TELEGRAM_BOT_TOKEN"
CHAT_ID="$TELEGRAM_CHAT_ID"
MSG="✅ Claude fertig in $CLAUDE_CWD — $(date +%H:%M)"

curl -s "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
  -d "chat_id=${CHAT_ID}" \
  -d "text=${MSG}" > /dev/null

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "python3 -c \"import json,time; open('/tmp/agent_heartbeat.json','w').write(json.dumps({'epoch':int(time.time()),'status':'idle','session':'$CLAUDE_SESSION_ID'}))\""
      }]
    }]
  }
}

Sicherheit und Exit-Codes

Hooks haben direkten Einfluss auf Claude Code. Die wichtigsten Regeln:

• Hooks laufen mit deinen Berechtigungen — sie können alles, was du im Terminal kannst
• Keine Schleifen — ein Hook darf nicht Claude triggern, der wieder den Hook triggert
• Timeout: Hooks haben ein Standard-Timeout von 60 Sekunden
• Sensitive Hooks (mit API-Keys) in settings.local.json legen — nicht in Git einchecken
• Stdout des Hooks wird Claude als Kontext übergeben — nutze es für Feedback

Hooks + CLAUDE.md kombinieren

Die mächtigste Kombination: Hooks übernehmen deterministisches Verhalten, CLAUDE.md definiert das Reasoning. Beispiel aus unserer Produktions-Infrastruktur:

# CLAUDE.md (Verhaltensebene)
## Commit-Regeln
- Nach jedem abgeschlossenen Task committen
- Format: [rolle] task-N: kurze Beschreibung
- Niemals mehr als 5 Dateien pro Commit

# settings.json (Enforcement-Ebene)
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "bash ~/.claude/hooks/auto-commit.sh"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash ~/.claude/hooks/bash-guard.sh"
      }]
    }]
  }
}

Das Ergebnis: CLAUDE.md sagt Claude wie es denken soll, Hooks stellen sicher dass bestimmte Aktionen immer passieren — unabhängig vom Reasoning.

Häufige Fehler mit Hooks

1. Hook blockiert Claude dauerhaft

Ein fehlerhafter PreToolUse-Hook der immer Exit-Code 2 zurückgibt, blockiert alle Tool-Aufrufe. Lösung: Hooks immer lokal testen bevor sie aktiviert werden. bash hook-script.sh direkt im Terminal ausführen.

2. Sensitive Daten in settings.json

API-Keys direkt in der Hook-Konfiguration landen schnell im Git. Besser: Umgebungsvariablen in settings.local.json und diese Datei in .gitignore.

3. Hook-Output überlädt Claudes Kontext

Wenn ein Hook sehr viel Output produziert, wird dieser als Kontext an Claude übergeben — und belegt Context-Window. Hooks sollten daher nur relevante, kurze Ausgaben produzieren. Verbose-Output umleiten: command >> /log/file 2>&1; echo "OK"