Claude Code Hooks: Der vollständige Leitfaden

Wer mit Claude Code arbeitet, kennt das Gefühl: Immer wieder dieselben manuellen Schritte, immer wieder die gleichen Prüfungen nach jedem Befehl. Genau hier setzen Claude Code Hooks an – ein mächtiges System zur Automatisierung von Entwicklungs-Workflows, das direkt in die Befehlsverarbeitung von Claude eingreift.

In diesem Leitfaden erfährst du alles, was du über Hooks wissen musst: von den Grundlagen über die JSON-Konfiguration bis hin zu fortgeschrittenen Agent-Hooks mit echten Entscheidungslogiken.

Was sind Claude Code Hooks? Grundlagen und Konzepte

Claude Code Hooks sind benutzerdefinierte Automatisierungsregeln, die sich in den Lebenszyklus von Tool-Aufrufen einklinken. Sie ermöglichen es, vor oder nach der Ausführung eines Werkzeugs automatisch bestimmte Aktionen auszulösen – ohne manuellen Eingriff.

Stell dir einen Hook als eine Art Auslöser vor: Sobald Claude ein bestimmtes Tool aufruft – etwa einen Bash-Befehl ausführt oder eine Datei schreibt – prüft das System, ob ein passender Hook konfiguriert ist. Ist das der Fall, wird die definierte Aktion automatisch gestartet.

Das Grundprinzip folgt einem klaren Muster: Ein Trigger definiert, wann der Hook feuert. Ein Matcher legt fest, auf welche Tools oder Befehle er anspricht. Und eine Action bestimmt, was passiert – ob ein Prompt verarbeitet, ein Shell-Befehl ausgeführt oder ein Agent gestartet wird.

Arten von Claude Code Hooks im Überblick

Claude Code unterscheidet grundsätzlich zwischen zwei Haupttypen von Hooks: Prompt-basierten und Agent-basierten Hooks. Daneben gibt es weitere spezialisierte Hook-Varianten, die auf bestimmte Ereignisse im Werkzeug-Lebenszyklus reagieren.

Ein Überblick über alle verfügbaren Hook-Typen:

PreToolUse-Hook: Wird ausgeführt, bevor Claude ein Tool verwendet. Ideal für Validierungen und Vorab-Prüfungen.
PostToolUse-Hook: Läuft nach erfolgreicher Tool-Ausführung. Nützlich für Logging, Tests oder Follow-up-Aktionen.
Notification-Hook: Reagiert auf interne Benachrichtigungen von Claude Code, etwa bei Statusänderungen.
Stop-Hook: Wird ausgelöst, wenn Claude die Bearbeitung einer Aufgabe abschließt.
SubagentStop-Hook: Entspricht dem Stop-Hook, aber für Subagenten innerhalb einer Sitzung.

Jeder dieser Hook-Typen lässt sich mit unterschiedlichen Action-Typen kombinieren. Damit ergibt sich eine flexible Matrix aus Auslösezeitpunkten und Reaktionsformen, die nahezu jeden Automatisierungsfall abdeckt.

Prompt-basierte Hooks: Einfache Automatisierung ohne Code

Der einfachste Hook-Typ ist der Prompt-Hook. Hier wird bei Auslösung ein vorformulierter Prompt an Claude gesendet, der dann wie eine normale Anfrage verarbeitet wird. Das ist besonders praktisch für einfache Prüfungen und Benachrichtigungen.

Ein typischer Anwendungsfall: Nach jedem erfolgreichen Bash-Befehl soll Claude automatisch prüfen, ob neue Fehler im Log aufgetaucht sind. Dafür benötigt man keinen einzigen Zeile eigenen Code – nur eine kurze JSON-Konfiguration und einen gut formulierten Prompt.

Der Aufbau eines Prompt-Hooks in der settings.json sieht so aus:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Prüfe die Ausgabe des letzten Bash-Befehls auf Fehlermeldungen und weise mich auf kritische Probleme hin."
          }
        ]
      }
    ]
  }
}

Die Stärke von Prompt-Hooks liegt in ihrer Einfachheit. Es ist kein externes Skript notwendig, keine Programmierkenntnisse vorausgesetzt – nur ein klarer Prompt und das richtige JSON-Schema. Gleichzeitig ist diese Variante auf die Fähigkeiten von Claude selbst beschränkt: Sie kann keine externen Systeme ansprechen oder komplexe Entscheidungsbäume abarbeiten.

Beispiele für sinnvolle Prompt-Hooks

Prompt-Hooks eignen sich besonders gut für wiederkehrende Review-Aufgaben. Hier einige bewährte Beispiele aus der Praxis:

Code-Review nach File-Write: Automatische Qualitätsprüfung nach jedem Schreibvorgang.
Sicherheits-Check vor Bash: Warnung bei potenziell gefährlichen Shell-Kommandos.
Dokumentationserinnerung: Hinweis, wenn eine neue Funktion ohne Docstring erstellt wurde.
Commit-Message-Validierung: Prüfung des Stils vor jedem Git-Commit.

Diese Use Cases zeigen: Prompt-Hooks sind das Schweizer Taschenmesser für alle, die schnell und ohne Overhead Automatisierungen einrichten möchten.

Aus der Praxis in Ihren Betrieb

Was wäre bei Ihnen automatisierbar?

Im kostenlosen Prozess-Audit zeigen wir Ihnen in 30 Minuten konkret, welche 3 Automationen sich bei Ihnen sofort lohnen, mit Einsparungs-Schätzung als PDF.

Prozess-Audit sichern

Agent-basierte Hooks: Komplexe Workflows mit KI-Agenten

Agent-Hooks gehen deutlich weiter als einfache Prompt-Hooks. Statt nur einen Prompt zu senden, starten sie einen vollwertigen KI-Agenten – mit eigenem Kontext, eigenen Tools und der Fähigkeit, mehrstufige Aufgaben selbstständig abzuarbeiten.

Das öffnet die Tür zu echten Automatisierungs-Pipelines: Ein Agent kann nach einem fehlgeschlagenen Test eigenständig die Fehlerursache analysieren, einen Fix vorschlagen und diesen direkt anwenden – alles ohne menschliches Zutun. Wer mehr über die Grundlagen von KI-Agenten erfahren möchte, findet auf unserer Seite zu Workflow Automation weiterführende Informationen.

Die Konfiguration eines Agent-Hooks erweitert die bekannte JSON-Struktur um den Typ agent:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "agent",
            "agent": {
              "prompt": "Analysiere den Exit-Code und die Ausgabe des letzten Befehls. Falls Fehler vorliegen, identifiziere die Ursache und schlage automatisch einen Fix vor.",
              "tools": ["Read", "Edit", "Bash"]
            }
          }
        ]
      }
    ]
  }
}

Wann Agent-Hooks sinnvoll sind

Agent-Hooks sollten dann eingesetzt werden, wenn einfache Prompts nicht ausreichen. Die wichtigsten Szenarien:

Automatisierte Test-Reparatur: Agent analysiert fehlgeschlagene Tests und korrigiert Code eigenständig.
Dependency-Management: Nach dem Editieren einer requirements.txt wird automatisch geprüft, ob alle Pakete kompatibel sind.
Kontinuierliche Dokumentation: Jede Code-Änderung triggert einen Agenten, der die README aktuell hält.
Security-Auditing: Ein spezialisierter Agent prüft jeden neuen Code auf Sicherheitslücken.

Das Potenzial von Agent-Hooks ist enorm – gleichzeitig steigt damit auch die Verantwortung für eine sorgfältige Konfiguration. Ein schlecht definierter Agent kann unerwünschte Aktionen auslösen und bestehenden Code überschreiben.

Hook-Konfiguration: JSON-Struktur und Syntax erklärt

Das Herzstück jeder Hook-Einrichtung ist die settings.json im Claude Code Verzeichnis. Diese JSON-Datei definiert alle Hooks, ihre Trigger, Matcher und zugehörigen Aktionen. Ein genaues Verständnis der Struktur ist unerlässlich für stabile Automatisierungen.

Die grundlegende Hierarchie der JSON-Konfiguration folgt diesem Schema:

{
  "hooks": {
    "[HookEvent]": [
      {
        "matcher": "[ToolName oder Regex]",
        "hooks": [
          {
            "type": "[prompt | agent | shell]",
            // Weitere type-spezifische Felder
          }
        ]
      }
    ]
  }
}

Die äußere Ebene definiert den Hook-Event-Typ (z.B. PreToolUse oder PostToolUse). Darunter folgt ein Array von Hook-Objekten, die jeweils einen Matcher und ein Array von auszuführenden Aktionen enthalten.

Alle konfigurierbaren Felder im Detail

Feld	Typ	Beschreibung	Pflichtfeld
`matcher`	String / Regex	Welches Tool oder welcher Befehl den Hook auslöst	Ja
`type`	Enum	Art des Hooks: prompt, agent oder shell	Ja
`prompt`	String	Der Prompt-Text für Prompt-Hooks	Bei type: prompt
`agent`	Object	Agent-Konfiguration mit prompt und tools	Bei type: agent
`command`	String	Shell-Befehl für Shell-Hooks	Bei type: shell
`timeout`	Integer	Maximale Ausführungszeit in Millisekunden	Nein

Das Timeout-Feld ist oft unterschätzt, aber äußerst wichtig: Ohne definiertes Timeout kann ein hängender Hook die gesamte Claude Code Sitzung blockieren. Für produktive Umgebungen empfiehlt sich immer ein expliziter Timeout-Wert.

Mehrere Hooks pro Event kombinieren

Innerhalb eines Hook-Events können mehrere Matcher-Objekte und pro Matcher auch mehrere Hook-Aktionen definiert werden. Diese werden sequenziell abgearbeitet:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Prüfe Syntax und Stil der gerade geschriebenen Datei."
          },
          {
            "type": "shell",
            "command": "echo 'File write detected' >> /tmp/claude-audit.log"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Überprüfe die Bash-Ausgabe auf Fehler."
          }
        ]
      }
    ]
  }
}

Diese Kombinierbarkeit macht das Hook-System besonders mächtig: Logging, Qualitätsprüfung und Agent-Aktionen können gleichzeitig auf dasselbe Ereignis reagieren.

Matcher und Trigger: Wann und wie Hooks ausgelöst werden

Der Matcher bestimmt, welche Tool-Aufrufe einen Hook aktivieren. Das klingt einfach – bietet aber erhebliche Flexibilität durch die Unterstützung regulärer Ausdrücke.

Ein einfacher Matcher reagiert auf ein spezifisches Tool:

{
  "matcher": "Bash"
}

Ein Regex-Matcher kann mehrere Tools gleichzeitig erfassen oder auf bestimmte Muster im Tool-Input reagieren:

{
  "matcher": "^(Bash|Read|Write)$"
}

Für maximale Kontrolle lassen sich Matcher auch auf den Inhalt des Tool-Inputs anwenden – also nicht nur auf den Tool-Typ, sondern auf die eigentlichen Parameter. Das ermöglicht hochspezifische Trigger wie “nur wenn ein Python-File editiert wird” oder “nur bei Git-Commit-Befehlen”.

Tool-spezifische Matcher-Strategien

In der Praxis haben sich folgende Matcher-Muster als besonders nützlich erwiesen:

Wildcard-Matcher: "matcher": ".*" – reagiert auf alle Tools, ideal für universelles Logging.
File-Typ-Filter: Kombination aus Write-Matcher und Input-Analyse für spezifische Dateitypen.
Command-Pattern: Regex auf Bash-Input, um nur bestimmte Shell-Kommandos zu triggern.
Negations-Muster: Komplexere Regex-Ausdrücke, die bestimmte Tools explizit ausschließen.

Ein wichtiger Punkt: Matcher sind case-sensitiv. "Bash" und "bash" sind unterschiedliche Matcher. Im Zweifelsfall empfiehlt sich ein Blick in die offizielle Claude Code Dokumentation auf anthropic.com, die alle verfügbaren Tool-Namen auflistet.

Tool-Input und Tool-Exit: Hooks im Werkzeug-Lebenszyklus

Für ein tiefes Verständnis von Hooks ist es wichtig zu wissen, wie Claude Code intern mit Tool-Aufrufen umgeht. Jeder Tool-Aufruf durchläuft einen definierten Lebenszyklus mit klar abgegrenzten Phasen.

Die Phase vor der Ausführung – also der Tool-Input – ist der Moment, in dem PreToolUse-Hooks greifen. Hier stehen alle Parameter des geplanten Tool-Aufrufs zur Verfügung: Welches Tool soll verwendet werden, mit welchen Argumenten, in welchem Kontext?

Die Phase nach der Ausführung – der Tool-Exit – triggert PostToolUse-Hooks. Jetzt sind zusätzlich die Ergebnisse des Tool-Aufrufs verfügbar: War der Aufruf erfolgreich? Was hat das Tool zurückgegeben? Gab es Fehlermeldungen?

Zugriff auf Tool-Input und Output in Hooks

Hooks erhalten den Tool-Kontext automatisch übergeben. In Prompt-Hooks wird dieser Kontext dem Prompt vorangestellt, sodass Claude ihn direkt analysieren kann. In Shell-Hooks stehen relevante Informationen als Umgebungsvariablen zur Verfügung:

# Verfügbare Umgebungsvariablen in Shell-Hooks
CLAUDE_TOOL_NAME         # Name des aufgerufenen Tools
CLAUDE_TOOL_INPUT        # JSON-kodierter Tool-Input
CLAUDE_TOOL_OUTPUT       # JSON-kodierter Tool-Output (nur PostToolUse)
CLAUDE_TOOL_EXIT_CODE    # Exit-Code (nur für Bash-Tool)
CLAUDE_SESSION_ID        # ID der aktuellen Claude-Sitzung

Diese Variablen ermöglichen es, in Shell-Hooks gezielt auf bestimmte Tool-Outputs zu reagieren – etwa den Exit-Code eines Bash-Befehls auszulesen und bei Fehler (Exit-Code != 0) eine Warnung zu erzeugen.

PreToolUse-Hooks als Sicherheitsnetz

PreToolUse-Hooks haben eine besondere Fähigkeit: Sie können die Ausführung eines Tools verhindern. Wenn ein PreToolUse-Hook einen definierten Fehler-Exit-Code zurückgibt, bricht Claude Code die geplante Tool-Ausführung ab und informiert den Nutzer.

Das macht PreToolUse-Hooks zum idealen Werkzeug für Sicherheitsprüfungen:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "shell",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | python3 /scripts/check-dangerous-commands.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Das externe Python-Skript analysiert den geplanten Bash-Befehl und gibt bei erkannten gefährlichen Mustern (z.B. rm -rf /, dd if=) einen Fehler-Exit-Code zurück – womit Claude Code den Befehl nicht ausführt.

Praktische Beispiele: Claude Code Hooks in realen Projekten

Theorie ist gut, Praxis ist besser. Die folgenden Beispiele zeigen, wie Hooks in echten Entwicklungsprojekten eingesetzt werden können – von einfachen Logging-Setups bis hin zu vollautomatisierten CI/CD-Integrationen.

Beispiel 1: Automatisches Logging aller Dateiänderungen

Dieses Setup protokolliert jede Dateiänderung in einer Audit-Log-Datei – nützlich für Compliance-Anforderungen oder zur späteren Nachvollziehbarkeit von Code-Änderungen:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "^(Write|Edit)$",
        "hooks": [
          {
            "type": "shell",
            "command": "echo \"$(date -Iseconds) | $CLAUDE_TOOL_NAME | $(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path // .path // \"unknown\"')\" >> ~/claude-audit.log",
            "timeout": 3000
          }
        ]
      }
    ]
  }
}

Beispiel 2: Automatische Tests nach Code-Änderungen

Nach jeder Python-Datei-Änderung sollen automatisch die relevanten Unit-Tests ausgeführt werden. Dafür kombinieren wir einen Shell-Hook mit einem intelligenten Prompt-Hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "shell",
            "command": "FILE=$(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path'); if echo $FILE | grep -q '\\.py$'; then cd $(dirname $FILE) && python -m pytest --tb=short -q 2>&1 | tail -20; fi",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

Beispiel 3: Slack-Benachrichtigung bei Session-Ende

Wenn Claude eine Aufgabe abschließt, soll das Team automatisch per Slack informiert werden. Der Stop-Hook macht genau das möglich:

{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "shell",
            "command": "curl -s -X POST -H 'Content-type: application/json' --data '{\"text\":\"Claude hat die Aufgabe abgeschlossen ✅\"}' $SLACK_WEBHOOK_URL",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Beispiel 4: Automatische Dokumentations-Generierung

Dieser Agent-Hook generiert nach jeder Änderung an Python-Dateien automatisch aktualisierte Dokumentation:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "agent",
            "agent": {
              "prompt": "Analysiere die gerade gespeicherte Python-Datei. Falls neue Funktionen oder Klassen hinzugefügt wurden, aktualisiere automatisch die entsprechende docs/-Datei mit korrekten Docstrings und Verwendungsbeispielen.",
              "tools": ["Read", "Write", "Edit"]
            }
          }
        ]
      }
    ]
  }
}

Beispiel 5: Git-Workflow-Automatisierung

Wer Claude Code für größere Entwicklungsprojekte nutzt, kann den gesamten Git-Workflow automatisieren. Dieser Hook führt nach jeder Session automatisch einen strukturierten Commit durch:

{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "agent",
            "agent": {
              "prompt": "Prüfe, ob es uncommittete Änderungen gibt. Falls ja, erstelle einen aussagekräftigen Git-Commit mit einer beschreibenden Nachricht, die alle Änderungen zusammenfasst. Folge dabei der Conventional-Commits-Spezifikation.",
              "tools": ["Bash"]
            }
          }
        ]
      }
    ]
  }
}

Hooks mit Decision-Logic: Bedingte Automatisierung einrichten

Echte Produktionsumgebungen brauchen mehr als einfache If-Then-Regeln. Decision-Logic in Hooks ermöglicht es, je nach Kontext unterschiedliche Aktionen auszulösen – abhängig vom Ergebnis eines vorherigen Schritts, dem aktuellen Branch, der Tageszeit oder beliebigen anderen Bedingungen.

Die einfachste Form der Decision-Logic ist ein Shell-Skript im Shell-Hook:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "shell",
            "command": "/bin/bash -c 'EXIT_CODE=$(echo $CLAUDE_TOOL_EXIT_CODE); if [ \"$EXIT_CODE\" != \"0\" ]; then notify-send \"Claude: Fehler bei Bash-Ausführung\" \"Exit Code: $EXIT_CODE\"; fi'",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Externe Skripte für komplexe Logik

Bei komplexeren Entscheidungslogiken empfiehlt es sich, die Logik in externe Skripte auszulagern. Das hält die JSON-Konfiguration sauber und macht die Logik testbar und wiederverwendbar:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "shell",
            "command": "python3 ~/.claude/hooks/pre-bash-validator.py",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Das externe Python-Skript erhält den Tool-Input über Umgebungsvariablen und kann beliebig komplexe Analysen durchführen:

#!/usr/bin/env python3
# ~/.claude/hooks/pre-bash-validator.py
import os
import json
import sys

tool_input = json.loads(os.environ.get('CLAUDE_TOOL_INPUT', '{}'))
command = tool_input.get('command', '')

# Gefährliche Muster
dangerous_patterns = [
    'rm -rf /',
    'dd if=/dev/zero',
    'mkfs.',
    ':(){ :|:& };:',  # Fork-Bomb
]

for pattern in dangerous_patterns:
    if pattern in command:
        print(f"SICHERHEITSWARNUNG: Gefährliches Muster erkannt: {pattern}")
        sys.exit(1)  # Verhindert Tool-Ausführung

print("Sicherheitsprüfung bestanden.")
sys.exit(0)

Kontextabhängige Hooks mit Environment-Variablen

Manchmal sollen Hooks nur in bestimmten Umgebungen aktiv sein – etwa nur in der Produktionsumgebung oder nur auf dem main-Branch. Das lässt sich über Environment-Variablen steuern:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "shell",
            "command": "if [ \"$ENVIRONMENT\" = \"production\" ]; then /scripts/production-deploy-check.sh; fi",
            "timeout": 15000
          }
        ]
      }
    ]
  }
}

Diese Kombination aus JSON-Konfiguration und Shell-Logik ermöglicht ein hochflexibles Automatisierungssystem, das sich nahtlos an verschiedene Projektanforderungen anpassen lässt. Wer sein gesamtes KI-Workflow-Setup professionell aufsetzen möchte, findet bei der KI Agentur Automated umfassende Unterstützung.

Einschränkungen und häufige Fehler bei Claude Code Hooks

So mächtig Hooks sind – es gibt klare Grenzen und Fallstricke, die Entwickler kennen sollten. Wer sie ignoriert, riskiert instabile Automatisierungen oder unerwartetes Verhalten.

Die wichtigsten Einschränkungen im Überblick

Keine rekursiven Hooks: Ein Hook kann keine neuen Tool-Aufrufe auslösen, die wiederum Hooks triggern – das würde zu Endlosschleifen führen.
Timeout-Beschränkungen: Hooks dürfen die definierte maximale Ausführungszeit nicht überschreiten. Zu lang laufende Hooks werden abgebrochen.
Kein Zugriff auf Conversation-History: Hooks sehen nur den aktuellen Tool-Aufruf, nicht den gesamten Gesprächsverlauf.
Begrenzte Kontextübergabe: Daten zwischen verschiedenen Hooks derselben Session können nicht direkt geteilt werden – nur über externe Dateien oder Datenbanken.
Keine asynchronen Hooks: Hooks werden synchron ausgeführt. Lange Operationen blockieren den Haupt-Thread.

Häufige Konfigurationsfehler

In der Praxis begegnen einem immer wieder dieselben Fehler in Hook-Konfigurationen:

Der häufigste Fehler ist ungültiges JSON. Ein einziges fehlendes Komma oder eine falsch geschlossene Klammer macht die gesamte Konfiguration unbrauchbar. Empfehlenswert ist daher die Validierung mit einem JSON-Linter vor dem Speichern:

cat ~/.claude/settings.json | python3 -m json.tool

Ein weiterer verbreiteter Fehler ist das Vergessen des Timeouts bei Shell-Hooks, die externe Prozesse aufrufen. Ohne Timeout kann ein hängender Prozess Claude Code dauerhaft blockieren. Immer einen angemessenen Timeout setzen – für schnelle Checks 3-5 Sekunden, für Tests und Deploys 30-60 Sekunden.

Falsche Matcher sind ebenfalls eine häufige Fehlerquelle. Wenn ein Hook nicht feuert, liegt es oft daran, dass der Tool-Name falsch geschrieben ist (z.B. bash statt Bash). Die korrekten Tool-Namen immer in der Dokumentation nachschlagen.

Debugging von Hooks

Wenn ein Hook nicht wie erwartet funktioniert, hilft folgendes Vorgehen:

# Hook-Debugging: Alle Outputs in eine Log-Datei umleiten
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "shell",
            "command": "echo \"Hook triggered: $CLAUDE_TOOL_NAME\" >> /tmp/hook-debug.log 2>&1",
            "timeout": 3000
          }
        ]
      }
    ]
  }
}

Dieser universelle Debug-Hook protokolliert jeden Tool-Aufruf und bestätigt damit, ob die Hook-Infrastruktur grundsätzlich funktioniert. Sobald das bestätigt ist, kann man schrittweise die eigentliche Logik einfügen und testen.

Best Practices für skalierbare Hook-Architekturen

Hooks, die in kleinen Projekten gut funktionieren, können in größeren Codebases schnell zu Problemen führen – durch Performance-Einbußen, schwer wartbare Konfigurationen oder unerwartete Interaktionen. Folgende Best Practices helfen, Hook-Architekturen von Anfang an skalierbar zu gestalten.

Modularisierung durch externe Skripte

Die JSON-Konfiguration sollte so schlank wie möglich bleiben. Komplexe Logik gehört in externe Skripte, die versioniert, getestet und unabhängig gewartet werden können. Eine sinnvolle Verzeichnisstruktur für Hook-Skripte:

~/.claude/
├── settings.json          # Nur Konfiguration, keine Logik
├── hooks/
│   ├── pre-bash-check.py  # Sicherheitsprüfung vor Bash
│   ├── post-write-lint.sh # Linting nach File-Write
│   ├── post-test-notify.py # Benachrichtigung nach Tests
│   └── stop-git-commit.sh # Auto-Commit bei Session-Ende
└── lib/
    └── common.sh          # Gemeinsame Hilfsfunktionen

Performance-Optimierung

Hooks werden bei jedem zutreffenden Tool-Aufruf ausgeführt. In aktiven Sessions können das Hunderte von Aufrufen pro Stunde sein. Jeder Hook muss daher so schnell wie möglich sein:

Timeout defensiv setzen: Lieber zu niedrig als zu hoch – ein abgebrochener Hook ist besser als ein blockierter Workflow.
Früh aussteigen: Skripte sollten so früh wie möglich bei Nicht-Treffer beenden (fail-fast-Prinzip).
Caching nutzen: Wenn ein Hook häufig dieselben Prüfungen macht, Ergebnisse cachen (z.B. in /tmp-Dateien).
Parallelisierung vermeiden: Keine Hintergrundprozesse aus Hooks starten, da diese unkontrolliert weiter laufen.

Umgebungsvariablen für Flexibilität

Statt Werte hart in die Konfiguration zu kodieren, sollten sensible Daten und umgebungsabhängige Parameter als Environment-Variablen gesetzt werden:

# In ~/.bashrc oder ~/.zshrc
export CLAUDE_HOOK_SLACK_WEBHOOK="https://hooks.slack.com/services/xxx"
export CLAUDE_HOOK_LOG_DIR="/var/log/claude-hooks"
export CLAUDE_HOOK_ENV="development"

Das macht Hooks portabel und sicher – keine API-Keys in Git-Repositories, keine hartkodierten Pfade, die auf anderen Maschinen brechen.

Versionierung und Testing

Hook-Skripte sollten wie normaler Code behandelt werden: versioniert in Git, dokumentiert und automatisch getestet. Ein einfaches Test-Framework für Shell-Hooks:

#!/bin/bash
# test-hooks.sh

# Test: Gefährlicher Befehl wird blockiert
CLAUDE_TOOL_INPUT='{"command":"rm -rf /"}' \
python3 ~/.claude/hooks/pre-bash-check.py
if [ $? -eq 0 ]; then
  echo "FEHLER: Gefährlicher Befehl wurde nicht blockiert!"
  exit 1
fi
echo "✓ Sicherheits-Hook funktioniert korrekt"

# Test: Normaler Befehl wird durchgelassen
CLAUDE_TOOL_INPUT='{"command":"ls -la"}' \
python3 ~/.claude/hooks/pre-bash-check.py
if [ $? -ne 0 ]; then
  echo "FEHLER: Normaler Befehl wurde fälschlicherweise blockiert!"
  exit 1
fi
echo "✓ Normaler Befehl korrekt durchgelassen"

Hook-Dokumentation in settings.json

JSON unterstützt keine Kommentare – das ist ein bekanntes Problem bei größeren Konfigurationen. Als Workaround können beschreibende Felder genutzt werden, die von Claude Code ignoriert werden:

{
  "hooks": {
    "PostToolUse": [
      {
        "_description": "Sicherheits-Audit für alle Dateioperationen",
        "_version": "1.2.0",
        "_author": "DevOps Team",
        "matcher": "^(Write|Edit)$",
        "hooks": [
          {
            "type": "shell",
            "command": "~/.claude/hooks/security-audit.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Zentrales Hook-Management für Teams

In Teams sollten Hooks nicht auf jedem Entwicklerrechner individuell konfiguriert werden. Stattdessen empfiehlt sich ein zentrales Hook-Repository mit einem Installations-Skript:

#!/bin/bash
# install-team-hooks.sh

HOOKS_DIR="$HOME/.claude/hooks"
mkdir -p "$HOOKS_DIR"

# Team-Hooks herunterladen
git clone https://github.com/company/claude-hooks "$HOOKS_DIR/team"

# settings.json mit Team-Hooks mergen
python3 scripts/merge-settings.py \
  "$HOME/.claude/settings.json" \
  "$HOOKS_DIR/team/settings.json"

echo "Team-Hooks erfolgreich installiert ✓"

Für Unternehmen, die KI-gestützte Entwicklungs-Workflows professionell implementieren möchten, bietet sich auch eine Zusammenarbeit mit einem spezialisierten Dienstleister an – etwa über professionelle KI-Unterstützung, die auf individuelle Anforderungen zugeschnitten ist.

Fortgeschrittene Hook-Patterns für professionelle Workflows

Jenseits der Grundlagen gibt es eine Reihe fortgeschrittener Patterns, die in professionellen Entwicklungsumgebungen besonders wertvoll sind. Diese Patterns kombinieren mehrere Hook-Konzepte zu leistungsfähigen Automatisierungs-Pipelines.

Pipeline-Hooks: Mehrere Schritte verketten

Eine der mächtigsten Hook-Strategien ist die Verkettung mehrerer Hooks zu einer automatisierten Pipeline. Dabei triggert jeder Hook-Output den nächsten Schritt:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "shell",
            "command": "~/.claude/hooks/01-lint.sh && touch /tmp/lint-passed",
            "timeout": 15000
          },
          {
            "type": "shell",
            "command": "[ -f /tmp/lint-passed ] && ~/.claude/hooks/02-type-check.sh",
            "timeout": 30000
          },
          {
            "type": "shell",
            "command": "~/.claude/hooks/03-run-tests.sh",
            "timeout": 60000
          }
        ]
      }
    ]
  }
}

Kontextuelle Hooks basierend auf Projekttyp

Hooks können sich automatisch an den Projekttyp anpassen. Ein Shell-Skript erkennt anhand vorhandener Konfigurationsdateien, um welches Projekt es sich handelt:

#!/bin/bash
# ~/.claude/hooks/smart-lint.sh

PROJECT_DIR=$(pwd)

if [ -f "$PROJECT_DIR/package.json" ]; then
  # Node.js Projekt
  npx eslint . --ext .js,.ts 2>&1 | tail -20
elif [ -f "$PROJECT_DIR/pyproject.toml" ] || [ -f "$PROJECT_DIR/setup.py" ]; then
  # Python Projekt
  python -m flake8 . 2>&1 | tail -20
elif [ -f "$PROJECT_DIR/Cargo.toml" ]; then
  # Rust Projekt
  cargo clippy 2>&1 | tail -20
else
  echo "Projekttyp nicht erkannt – Linting übersprungen"
fi

Monitoring-Integration

Für Projekte mit strengen Qualitätsanforderungen können Hooks direkt in Monitoring-Systeme integriert werden:

#!/usr/bin/env python3
# ~/.claude/hooks/metrics-reporter.py

import os
import json
import time
import urllib.request

tool_name = os.environ.get('CLAUDE_TOOL_NAME', 'unknown')
session_id = os.environ.get('CLAUDE_SESSION_ID', 'unknown')

metric = {
    "metric": "claude.tool.usage",
    "value": 1,
    "timestamp": int(time.time()),
    "tags": {
        "tool": tool_name,
        "session": session_id,
        "project": os.path.basename(os.getcwd())
    }
}

# An Monitoring-API senden
data = json.dumps(metric).encode('utf-8')
req = urllib.request.Request(
    os.environ.get('METRICS_API_URL', 'http://localhost:9091/metrics'),
    data=data,
    headers={'Content-Type': 'application/json'}
)
try:
    urllib.request.urlopen(req, timeout=2)
except Exception:
    pass  # Metriken sind nicht kritisch – Fehler ignorieren

Fazit: Claude Code Hooks für produktivere Entwicklung nutzen

Claude Code Hooks sind ein Game-Changer für alle, die ihren Entwicklungs-Workflow automatisieren möchten. Von einfachen Prompt-Hooks für schnelle Qualitätsprüfungen bis hin zu komplexen Agent-basierten Pipelines – das System bietet für jeden Anwendungsfall die richtige Lösung.

Der Schlüssel zum Erfolg liegt in einer durchdachten, inkrementellen Einführung. Starte mit einfachen Shell-Hooks für Logging und Monitoring. Füge Prompt-Hooks für automatische Code-Reviews hinzu. Und steige erst dann auf Agent-Hooks um, wenn die einfacheren Varianten ihre Grenzen zeigen.

Besonders wertvoll werden Hooks in Kombination mit anderen Automatisierungstools. Wer Claude Code Hooks mit CI/CD-Pipelines, Monitoring-Systemen und Team-Kollaborationstools verknüpft, schafft ein ganzheitliches Entwicklungs-Ökosystem, das Qualität und Geschwindigkeit gleichzeitig steigert.

Die Investition in eine solide Hook-Architektur zahlt sich schnell aus: Weniger manuelle Schritte, weniger Fehler durch vergessene Prüfungen, mehr Zeit für die eigentliche Entwicklungsarbeit. Das ist letztendlich der Kern des Hook-Systems – nicht Magie, sondern intelligente Automatisierung an den richtigen Stellen.

FAQ zu Claude Code Hooks

Was ist ein Claude Code Hook?

Ein Claude Code Hook ist eine automatisch ausgeführte Aktion, die sich in den Lebenszyklus von Tool-Aufrufen in Claude Code einklinkt. Hooks können vor (PreToolUse) oder nach (PostToolUse) der Ausführung eines Tools ausgelöst werden. Sie ermöglichen Automatisierungen wie automatische Code-Reviews, Sicherheitsprüfungen, Logging oder die Ausführung externer Skripte – ohne manuellen Eingriff des Entwicklers.

Wie konfiguriere ich Hooks in JSON?

Hooks werden in der Datei ~/.claude/settings.json konfiguriert. Die grundlegende Struktur ist: ein Hook-Event-Typ (z.B. PostToolUse) als oberster Schlüssel, darunter ein Array von Matcher-Objekten, die definieren, welche Tools den Hook auslösen, und schließlich ein Array von Hook-Aktionen mit Type (prompt, agent oder shell) und den dazugehörigen Parametern. Die JSON-Datei muss nach jeder Änderung gespeichert werden und wird beim nächsten Tool-Aufruf aktiv.

Was ist der Unterschied zwischen Prompt-Hooks und Agent-Hooks?

Prompt-Hooks senden bei Auslösung einen vordefinierten Text-Prompt an Claude, der wie eine normale Anfrage verarbeitet wird. Sie sind einfach zu konfigurieren und benötigen keinen externen Code. Agent-Hooks hingegen starten einen vollwertigen KI-Agenten mit eigenem Kontext und eigenen Tool-Berechtigungen, der mehrstufige Aufgaben selbstständig abarbeiten kann. Prompt-Hooks eignen sich für einfache Reviews und Benachrichtigungen, Agent-Hooks für komplexe Automatisierungsaufgaben wie automatisches Bug-Fixing oder Dokumentations-Generierung.

Welche Einschränkungen haben Claude Code Hooks?

Die wichtigsten Einschränkungen sind: Hooks können keine rekursiven Tool-Aufrufe auslösen (kein Hook triggert andere Hooks über Tool-Aufrufe). Hooks werden synchron ausgeführt und können bei überschrittenem Timeout abgebrochen werden. Sie haben keinen Zugriff auf die gesamte Conversation-History, sondern nur auf den aktuellen Tool-Aufruf. Daten zwischen verschiedenen Hooks können nicht direkt geteilt werden. Außerdem sind Matcher case-sensitiv und müssen die exakten Tool-Namen aus der Claude Code Dokumentation verwenden.

Kann ein Hook die Ausführung eines Tools verhindern?

Ja – PreToolUse-Hooks können die Ausführung eines Tools verhindern. Wenn ein PreToolUse-Hook einen Fehler-Exit-Code (ungleich 0) zurückgibt, bricht Claude Code den geplanten Tool-Aufruf ab und informiert den Nutzer. Das macht PreToolUse-Hooks ideal für Sicherheitsprüfungen, etwa um gefährliche Shell-Kommandos zu blockieren oder zu verhindern, dass in Produktionsdateien geschrieben wird.

Wie debugge ich einen Hook, der nicht funktioniert?

Der einfachste Ansatz ist ein universeller Debug-Hook, der jeden Tool-Aufruf in eine Log-Datei schreibt. Damit lässt sich prüfen, ob die Hook-Infrastruktur grundsätzlich funktioniert. Häufige Fehlerursachen sind: ungültiges JSON in settings.json (Validierung mit python3 -m json.tool), falsch geschriebene Tool-Namen im Matcher, fehlende Ausführungsrechte für Shell-Skripte, zu kurze Timeouts oder Syntaxfehler im Shell-Command-String.

Sind Hook-Konfigurationen projektspezifisch oder global?

Claude Code unterstützt sowohl globale als auch projektspezifische Hook-Konfigurationen. Globale Hooks werden in ~/.claude/settings.json definiert und gelten für alle Projekte. Projektspezifische Hooks können in einer .claude/settings.json im Projektverzeichnis abgelegt werden. Bei Konflikten haben projektspezifische Einstellungen Vorrang vor globalen. Das ermöglicht flexible Setups, bei denen grundlegende Sicherheitsprüfungen global aktiv sind, während projektspezifische Tests und Linter nur im jeweiligen Projekt laufen.

Kann ich Shell-Hooks und Prompt-Hooks gleichzeitig für dasselbe Ereignis nutzen?

Ja, das ist ausdrücklich möglich und empfohlen. Innerhalb eines Matcher-Objekts können mehrere Hook-Aktionen unterschiedlicher Typen definiert werden. Sie werden sequenziell in der angegebenen Reihenfolge ausgeführt. So kann etwa ein Shell-Hook zunächst ein externes Lint-Skript ausführen, während ein anschließender Prompt-Hook Claude bittet, die Ergebnisse zu interpretieren und konkrete Verbesserungsvorschläge zu machen.