Claude Code Hooks: Was ist das und wie man es nutzt

Für Vibe Coders verändern Tools wie Anthropic's Claude Code die Art und Weise, wie Entwickler ihre Projekte schreiben, debuggen und verwalten. Claude Code fungiert als ein „agentisches Codierungswerkzeug“, das in Ihrem Terminal residiert und in der Lage ist, Ihre gesamte Codebasis zu verstehen, mit Ihrem Dateisystem zu interagieren, Befehle auszuführen und sogar das Web nach Dokumentation zu durchsuchen. Es zeichnet sich durch Aufgaben wie das Schreiben neuer Funktionen, das Beheben von Fehlern und das Refactoring von Code mittels natürlicher Sprachprompts aus.

Ein Kernmerkmal von Großen Sprachmodellen (LLMs) ist jedoch ihre probabilistische Natur. Während dies kreative Problemlösungen ermöglicht, kann es manchmal zu Unvorhersehbarkeit führen. Sie möchten vielleicht, dass bestimmte Aktionen – wie das Linting einer Datei nach ihrer Änderung oder das Ausführen von Tests nach dem Schreiben einer neuen Funktion – jedes einzelne Mal fehlerfrei ausgeführt werden. Sich darauf zu verlassen, dass das LLM sich in jedem Fall daran erinnert, dies zu tun, kann inkonsistent sein.

Hier kommen Claude Code Hooks ins Spiel. Hooks sind eine leistungsstarke Funktion, die eine deterministische, programmatische Kontrolle über das Verhalten von Claude Code bietet und sicherstellt, dass bestimmte Aktionen immer ausgeführt werden, anstatt sich darauf zu verlassen, dass das LLM sie ausführt.

Dieser Artikel dient als umfassender Leitfaden zum Verständnis, zur Konfiguration und zur Nutzung von Claude Code Hooks, um einen vollständig automatisierten und optimierten Entwicklungsworkflow zu erstellen.

Was sind Claude Code Hooks?

Im Kern sind Claude Code Hooks benutzerdefinierte Shell-Befehle, die automatisch an bestimmten Punkten im Lebenszyklus von Claude Code ausgeführt werden. Sie fungieren als Trigger, die Sie so konfigurieren können, dass sie vor oder nach bestimmten Aktionen ausgelöst werden, wodurch Sie Ihre eigene benutzerdefinierte Logik, Skripte und Befehle direkt in die Operationen von Claude integrieren können.

Hooks überbrücken die Lücke zwischen KI-gestützter Unterstützung und regelbasierter Automatisierung. Sie ermöglichen es Ihnen, Standards durchzusetzen, wiederkehrende Aufgaben zu automatisieren und externe Tools nahtlos und mit vollständiger Zuverlässigkeit in Ihren Workflow zu integrieren.

Es gibt vier wichtige Lebenszyklusereignisse, bei denen ein Hook ausgelöst werden kann:

1. PreToolUse: Wird *bevor* Claude ein bestimmtes Tool verwendet (z.B. vor dem Schreiben in eine Datei) ausgeführt.
2. PostToolUse: Wird *nachdem* ein Tool erfolgreich verwendet wurde (z.B. nachdem eine Datei geändert wurde) ausgeführt.
3. Notification: Wird immer dann ausgeführt, wenn Claude eine Benachrichtigung sendet (z.B. wenn Benutzereingaben benötigt werden oder eine lange Aufgabe abgeschlossen wurde).
4. Stop: Wird ausgeführt, wenn Claude die Generierung seiner Antwort beendet und stoppt.

Indem Sie diese Ereignisse ansprechen, können Sie leistungsstarke Automatisierungen erstellen, die den Best Practices der modernen Softwareentwicklung, wie z.B. Continuous Integration (CI)-Prüfungen, entsprechen, jedoch mit der Geschwindigkeit der lokalen Entwicklung.

Die Anatomie von Claude Code Hooks: Eine detaillierte Konfigurationsanalyse

Um Hooks zu verwenden, müssen Sie diese in Ihrer Claude Code-Einstellungsdatei definieren. Dies geschieht durch Hinzufügen einer [[hooks]]-Tabelle zu Ihrer settings.toml-Datei, die sich im Verzeichnis .claude/ Ihres Projekts befindet. Jede Hook-Konfiguration besteht aus einigen Schlüsselkomponenten.

# Beispiel-Hook in .claude/settings.toml

[[hooks]]
# Das Ereignis, das den Hook auslöst.
event = "PostToolUse" 

# (Optional) Bedingungen für die Ausführung des Hooks.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# Der auszuführende Shell-Befehl.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Ob der Befehl im Hintergrund ausgeführt werden soll.
run_in_background = false 

Lassen Sie uns jeden Teil im Detail aufschlüsseln.

Das Feld event in Claude Code Hooks (Erforderlich)

Dieser String gibt an, welches der vier Lebenszyklusereignisse den Hook auslöst.

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

Der hooks.matcher in Claude Code Hooks (Optional)

Der Matcher ermöglicht es Ihnen, präzise zu definieren, *wann* ein Hook ausgeführt werden soll. Wenn Sie den Matcher weglassen, wird der Hook für jede Instanz des angegebenen event ausgeführt. Zum Beispiel wird ein PostToolUse-Hook ohne Matcher nach *jedem* Tool-Aufruf ausgelöst.

Der Matcher verfügt über drei Felder, die Sie zum Filtern von Ereignissen verwenden können:

• tool_name: Ein String, der mit dem Namen des verwendeten Tools übereinstimmt. Dies ist perfekt, um bestimmte Aktionen wie edit_file, git_commit oder run_command anzusprechen.
• file_paths: Ein Array von Strings, die Glob-Muster enthalten. Der Hook wird nur ausgeführt, wenn die bei der Tool-Nutzung beteiligten Dateien einem dieser Muster entsprechen. Zum Beispiel zielt ["*.py"] auf alle Python-Dateien ab, während ["src/components/**/*.jsx"] auf JSX-Dateien in einem bestimmten Verzeichnis abzielt.
• query: Ein String, der mit der Eingabe eines Tools übereinstimmt. Dies ist nützlich für spezifischere Trigger, z.B. das Ausführen eines Hooks nur, wenn ein run_command-Tool mit einem Befehl verwendet wird, der npm enthält.

Das Feld command für Claude Code Hooks (Erforderlich)

Dies ist das Herzstück des Hooks – der Shell-Befehl, der ausgeführt wird, wenn die Trigger-Bedingungen erfüllt sind. Dieser Befehl läuft mit denselben Berechtigungen wie Ihr Benutzerkonto, sodass er alles tun kann, was Sie in Ihrem Terminal tun können.

Um Befehle dynamisch zu gestalten, stellt Claude Code eine Reihe von Umgebungsvariablen bereit, die mit Kontext aus dem Ereignis gefüllt werden, das den Hook ausgelöst hat.

Verfügbare Umgebungsvariablen:

• $CLAUDE_EVENT_TYPE: Der Typ des Ereignisses (PreToolUse, PostToolUse, etc.).
• $CLAUDE_TOOL_NAME: Der Name des verwendeten Tools (z.B. edit_file).
• $CLAUDE_TOOL_INPUT: Die rohen Eingabeparameter, die im JSON-Format an das Tool übergeben wurden.
• $CLAUDE_FILE_PATHS: Eine durch Leerzeichen getrennte Liste von Dateipfaden, die für den Tool-Aufruf relevant sind. Dies ist unglaublich nützlich, um Dateien an Formatierer, Linter oder Test-Runner zu übergeben.
• $CLAUDE_NOTIFICATION: Der Inhalt der Benachrichtigungsnachricht (nur für das Notification-Ereignis).
• $CLAUDE_TOOL_OUTPUT: Die Ausgabe der Tool-Ausführung (nur für das PostToolUse-Ereignis).

Die Einstellung run_in_background für Claude Code Hooks (Optional)

Dies ist ein boolescher Wert (true oder false). Wenn auf true gesetzt, wird der Befehl des Hooks in einem separaten Prozess ausgeführt, und Claude wartet nicht auf dessen Abschluss, bevor er fortfährt. Dies ist ideal für langwierige Aufgaben wie umfassende Testsuiten oder Build-Prozesse, die Sie nicht blockieren möchten, um nachfolgende Aktionen von Claude auszuführen. Der Standardwert ist false.

Praktische Anwendungsfälle und Beispiele für Claude Code Hooks

Die wahre Stärke von Hooks offenbart sich, wenn Sie sie auf reale Entwicklungsworkflows anwenden. Hier sind einige praktische Beispiele, um Ihnen den Einstieg zu erleichtern.

1. Automatisches Linting und Formatieren mit Claude Code Hooks

Erzwingen Sie automatisch einen konsistenten Codestil in Ihrem Projekt. Dieser Hook führt den ruff-Linter und den black-Formatierer für jede Python-Datei aus, die Claude bearbeitet.

Datei: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Befehl zum Linting, Beheben und Formatieren der bearbeiteten Python-Dateien.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Automatisches Ausführen von Tests mit Claude Code Hooks

Eine Kernpraxis der testgetriebenen Entwicklung (TDD) ist es, Tests zu schreiben und dann Code zu schreiben, um diese Tests zu bestehen, wobei man iteriert, bis alles funktioniert. Sie können den Schritt „Tests ausführen“ mit einem Hook automatisieren. Dieses Beispiel führt pytest aus, wann immer eine Datei im Verzeichnis src/ oder tests/ geändert wird.

Datei: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Tests können langsam sein, im Hintergrund ausführen.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Befehl zum Ausführen der Testsuite.
command = "pytest"

3. Benutzerdefinierte Desktop-Benachrichtigungen über Claude Code Hooks

Wenn Sie Claude bitten, eine langwierige Aufgabe auszuführen, könnten Sie sich von Ihrem Computer entfernen. Dieser Hook verwendet ein Befehlszeilentool wie ntfy (einen einfachen HTTP-basierten Pub-Sub-Benachrichtigungsdienst), um eine Push-Benachrichtigung an Ihr Telefon oder Ihren Desktop zu senden, wenn Claude Ihre Aufmerksamkeit benötigt.

Datei: .claude/settings.toml

[[hooks]]
event = "Notification"

# Sendet den Benachrichtigungsinhalt an ein öffentliches ntfy.sh-Thema.
# Sie können Ihr eigenes für den Datenschutz hosten.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Pre-Commit-Sanity-Checks mit Claude Code Hooks

Ähnlich wie bei Git-Hooks können Sie Claude Code Hooks verwenden, um die Qualität *vor* einem Commit sicherzustellen. Dieses Beispiel führt ein benutzerdefiniertes Skript aus, um nach API-Schlüsseln zu suchen oder andere Validierungsschritte durchzuführen, kurz bevor Claude das git_commit-Tool verwenden darf.

Datei: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Befehl zum Ausführen eines Pre-Commit-Prüfskripts.
# Das Skript sollte mit einem Nicht-Null-Code beendet werden, um den Commit zu stoppen.
command = "sh ./.claude/pre-commit-checks.sh"

Einrichtung und Debugging Ihrer Claude Code Hooks

Der Einstieg in Hooks ist unkompliziert, aber die Überprüfung und das Debugging sind entscheidend, um sicherzustellen, dass sie wie erwartet funktionieren.

1. Konfiguration erstellen: Stellen Sie sicher, dass Sie eine .claude/settings.toml-Datei im Stammverzeichnis Ihres Projekts haben. Fügen Sie dort Ihre [[hooks]]-Konfigurationen hinzu.
2. Konfiguration überprüfen: Nachdem Sie Ihre settings.toml-Datei gespeichert haben, führen Sie den Befehl /hooks in der Claude Code Terminal-Oberfläche aus. Dieser spezielle Befehl zeigt Ihre aktuell geladenen Hook-Konfigurationen an, sodass Sie sofort sehen können, ob Claude sie korrekt geparst hat.
3. Auf Fehler prüfen:

• Ungültiges TOML: Stellen Sie sicher, dass Ihre settings.toml-Datei eine gültige Syntax hat. Eine falsch platzierte Klammer oder Anführungszeichen kann das Laden verhindern.
• Befehlsprobleme: Testen Sie Ihren command direkt in Ihrer Shell, um sicherzustellen, dass er wie erwartet funktioniert. Suchen Sie nach Tippfehlern und stellen Sie sicher, dass die erforderlichen ausführbaren Dateien (black, pytest, ntfy usw.) in Ihrem System-PATH enthalten sind.
• Debugging-Variablen: Um zu sehen, welche Werte die Umgebungsvariablen enthalten, verwenden Sie echo, um sie in eine Protokolldatei zu schreiben. Zum Beispiel: command = "echo 'Tool: $CLAUDE_TOOL_NAME, Files: $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

Fazit: Die Stärke von Claude Code Hooks

Claude Code Hooks heben das Tool von einem hochleistungsfähigen Codierungsassistenten zu einem vollständig integrierten, deterministischen Entwicklungspartner. Durch die Definition einfacher, leistungsstarker Regeln können Sie die alltäglichen, aber kritischen Teile Ihres Workflows automatisieren und sich so auf die komplexen, kreativen Aspekte der Softwareentwicklung konzentrieren. Ob es darum geht, die Codequalität durchzusetzen, Ihren TDD-Zyklus zu vereinfachen oder mit Drittanbieterdiensten zu integrieren, Hooks bieten den robusten Rahmen, der notwendig ist, um Claude Code an Ihre genauen Bedürfnisse anzupassen.

Wenn Sie sich mit den Funktionen von Claude Code vertraut gemacht haben, beginnen Sie klein mit einem einfachen Formatierungs-Hook und erkunden Sie dann komplexere Automatisierungen. Sie werden schnell feststellen, dass diese Funktion unerlässlich ist, um eine vorhersehbare, effiziente und wirklich personalisierte KI-gestützte Entwicklungsumgebung aufzubauen.