Claude Code Hooks: Events, Beispiele und wie sie funktionieren

Hook-Events in Claude Code

Die Referenz listet mehr als dreißig Events. Das hier sind die, die die meisten Hooks nutzen; ein matcher beschränkt einen Hook auf bestimmte Tools, Dateien oder Quellen.

Wo Hooks hingehören

Beispiele für Claude Code Hooks, Schritt für Schritt

Füge jeden Block unter dem Schlüssel hooks einer Settings-Datei ein; hat die Datei schon ein hooks-Objekt, ergänze das Event als weiteren Schlüssel daneben, statt es zu ersetzen. Führe /hooks aus, um zu prüfen, ob Claude Code den Hook geladen hat. Du kannst Claude auch bitten, den Hook für dich zu schreiben.

1. Lass dich per Desktop-Benachrichtigung rufen, wenn Claude dich braucht

   Ein Notification-Hook in ~/.claude/settings.json. Dieser nutzt osascript unter macOS; unter Linux nimmst du notify-send, unter Windows PowerShell.

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. Formatiere jede Datei automatisch, die Claude bearbeitet

   Ein PostToolUse-Hook mit dem Matcher Edit|Write liest mit jq den bearbeiteten Pfad aus dem JSON auf stdin und lässt Prettier darüber laufen. Leg ihn in .claude/settings.json ab, damit das ganze Team ihn nutzt.

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
           ]
         }
       ]
     }
   }

3. Blockiere einen gefährlichen Befehl

   Ein PreToolUse-Hook auf Bash führt dieses Skript aus. Exit-Code 2 blockiert den Aufruf, und was du nach stderr schreibst, wird zu Claudes Feedback, damit es umsteuern kann. Exit 0 heißt keine Entscheidung, die normalen Berechtigungen gelten also weiter.

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh, läuft als PreToolUse-Hook auf Bash
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # wird zu Claudes Feedback
     exit 2                                               # 2 = Aktion blockieren
   fi
   
   exit 0  # keine Entscheidung: der normale Berechtigungsablauf greift

4. Lass Claude weiterarbeiten, bis die Aufgabe erledigt ist

   Ein Stop-Hook vom Typ prompt fragt ein Modell, ob alles fertig ist. Antwortet es mit ok: false, arbeitet Claude weiter, mit dem reason als nächster Anweisung. Das ist das klassische Beispiel für einen Stop-Hook.

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

Quelle: Claude-Code-Dokumentation, Automate actions with hooks

Wie Hooks entscheiden, was passiert

• Eingabe: Jeder Hook bekommt das Event als JSON auf stdin, etwa den Tool-Namen und tool_input, die Session-ID und cwd.
• Exit 0: kein Einwand. Bei einigen Events, etwa SessionStart und UserPromptSubmit, wird einfacher stdout-Text in Claudes Kontext aufgenommen.
• Exit 2: blockieren, sofern das Event es zulässt. Stderr geht je nach Event an Claude oder an dich.
• JSON auf stdout: feinere Steuerung, etwa hookSpecificOutput mit einer Berechtigungsentscheidung, updatedInput, um die Eingabe eines Tools umzuschreiben, oder additionalContext.
• Andere Exit-Codes: meist ein nicht blockierender Fehler, außer der Hook setzt onFailure: "block".
• Passende Hooks für dasselbe Event laufen parallel.

Command-, Prompt-, Agent- und HTTP-Hooks

Hooks vs. Skills vs. CLAUDE.md und weitere Stolperfallen

• CLAUDE.md und Skills sind Anweisungen, die Claude meistens befolgt; Hooks laufen immer. Alles, was nie übersprungen werden darf, gehört in einen Hook.
• PostToolUse kann eine bereits ausgeführte Aktion nicht rückgängig machen; nutze PreToolUse, um sie zu verhindern.
• Stop löst jedes Mal aus, wenn Claude eine Antwort beendet, nicht nur am Ende einer Aufgabe, und nicht, wenn der Nutzer unterbricht.
• Hooks können selbst keine Slash-Commands ausführen und keine Tools aufrufen; sie antworten nur über Exit-Codes, stdout, stderr oder JSON.
• "disableAllHooks": true schaltet Hooks ab; verwaltete Hooks laufen trotzdem, außer die verwalteten Einstellungen schalten sie ebenfalls ab.
• Hooks gelten nur für deine eigene Claude-Code-Installation. Organisationsweite Prüfungen für alle Claude-Produkte sind ein anderes Feature: Claude Inference Hooks.
• Ein PreToolUse-Hook, der Testausgaben filtert, ist außerdem einer der besten Wege, den Token-Verbrauch zu senken.

Hooks halten Claude Code in der Spur. Crewmark hält es am Arbeiten.

Hooks machen einen unbeaufsichtigten Agenten erst sicher: Formatierung, Tests und Leitplanken laufen jedes Mal. Crewmark macht aus einer Session von Claude Code, Codex, DeepSeek Harness oder OpenCode einen KI-Mitarbeiter mit Rolle, Ziel und Arbeitszeiten und weckt ihn per Heartbeat, damit er das nächste Issue von einem Board übernimmt, mit den Hooks deines Projekts an Ort und Stelle.

1. Committe deine Hooks

   Hooks aus .claude/settings.json laden in der Session des Mitarbeiters genau wie in deiner, seine Änderungen werden also formatiert und riskante Befehle blockiert.

2. Lass den Heartbeat die Arbeit starten

   Während seiner Arbeitszeiten wacht der Mitarbeiter alle 15, 30 oder 60 Minuten in derselben Unterhaltung auf; siehe wie du Claude Code proaktiv machst.

3. Beantworte nur, was dich braucht

   Er kommentiert seine Issues und schreibt dir, wenn er eine Entscheidung braucht. Lies, was ein KI-Mitarbeiter ist.

FAQ zu Claude Code Hooks