Claude Code – Anpassungen für Power-User: So konfigurieren Sie Hooks

Selbst bei einem eigentlich reibungslosen Claude Code-Workflow kann es im Laufe der Zeit zu Problemen kommen. Jedes Mal, wenn Claude eine Datei schreibt, muss Prettier manuell ausgeführt werden. Bei jeder Ausführung von npm test wird dieselbe Berechtigungsabfrage angezeigt. Zu Beginn jeder Sitzung wird derselbe standardmäßige Projektkontext in die erste Nachricht eingefügt.

Die gute Nachricht? Hooks beseitigen diese Probleme. Sie fungieren als Auslöser, die Sie so konfigurieren können, dass sie vor oder nach bestimmten Aktionen ausgelöst werden. So können Sie benutzerdefinierte Logik, Skripte und Befehle direkt in die Vorgänge von Claude einfügen.

In diesem Artikel wird die erweiterte Konfiguration für Entwickler beschrieben, die bereits mit den Grundlagen von Claude Code vertraut sind. Am Ende dieses Artikels werden Sie die acht Hook-Typen kennen, wissen, wann Sie sie verwenden sollten, wie Sie sie konfigurieren und wie Sie sie debuggen, wenn etwas schief geht.

Schauen wir uns das Ganze einmal etwas näher im Detail an.

Was ist ein Hook?

Ein Hook ist ein benutzerdefinierter Shell-Befehl, den Sie erstellen, um automatisch ausgeführt zu werden, wenn ein bestimmtes Ereignis in Ihrer Claude Code-Sitzung eintritt – z. B. wenn Claude im Begriff ist, eine Datei zu schreiben, oder wenn Sie einen Prompt senden. Sie können Hooks für eine Vielzahl von Zwecken einrichten: Aktionen abfangen, bevor sie ausgeführt werden, Agentenkontext hinzufügen, Genehmigungen automatisieren oder Vorgänge blockieren, bevor sie stattfinden.

Hooks werden in Ihren Einstellungsdateien mit einer JSON-Struktur mit Ereignisnamen, Matchern (um zu filtern, welche Tools den Hook auslösen) und den auszuführenden Befehlen konfiguriert. Sie werden in Ihrer lokalen Umgebung mit Ihren Benutzerberechtigungen ausgeführt, erhalten Informationen über das auslösende Ereignis über stdin und kommunizieren über Exit-Codes und stdout. So können Sie das Verhalten von Claude Code präzise steuern, ohne das Tool selbst ändern zu müssen.

Warum Sie Hooks in Claude Code verwenden sollten?

Hooks lösen drei Problemkategorien.

Erstens eliminieren sie sich wiederholende manuelle Schritte. Anstatt Ihren Formatierer nach jeder Dateiänderung auszuführen, erledigt ein PostToolUse-Hook dies automatisch. Anstatt npm test zum hundertsten Mal zu genehmigen, genehmigt ein PermissionRequest-Hook dies automatisch.

Zweitens setzen Hooks projektspezifische Regeln automatisch durch. Sie können gefährliche Befehle blockieren, bevor sie ausgeführt werden, Dateipfade vor dem Schreiben validieren oder sicherstellen, dass Benennungskonventionen eingehalten werden. Diese Sicherheitsvorkehrungen werden jedes Mal ausgeführt, nicht nur wenn Sie daran denken, sie zu überprüfen.

Drittens fügen Hooks ohne manuellen Aufwand dynamischen Kontext ein. Ein SessionStart-Hook kann Claude Ihren aktuellen Git-Status und die TODO-Liste übermitteln. Ein UserPromptSubmit-Hook kann jeder Anfrage Ihre Sprint-Prioritäten hinzufügen. Claude bleibt auf dem neuesten Stand, ohne dass Sie sich wiederholen müssen.

Hook-Typen in Claude Code und wann sie verwendet werden sollten

Claude Code bietet acht Hook-Ereignisse an, die den gesamten Lebenszyklus einer Sitzung abdecken – vom Start über die Tool-Ausführung bis hin zum Abschluss. Jeder startet zu einem bestimmten Zeitpunkt, sodass Sie genau steuern können, wann Ihre Automatisierung ausgeführt wird. Die Wahl des richtigen Hooks davon hängt, was Sie erreichen möchten.

Hooks auf einen Blick

PreToolUse

Dieser Hook wird am häufigsten verwendet und wird ausgelöst, nachdem Claude ein Tool für die Verwendung ausgewählt hat, aber noch bevor das Tool tatsächlich zum Einsatz kommt. Ihr Skript kann die geplante Aktion überprüfen und genehmigen, blockieren, eine Benutzerbestätigung anfordern oder die Parameter ändern, indem es einen Matcher verwendet, um zu filtern, welche Tools diesen Hook auslösen.

Dieses PreToolUse-Hook-Beispiel wertet die Dateischreibvorgänge aus, bevor sie ausgeführt werden. Claude überprüft die geplante Aktion anhand der angegebenen Kriterien und kann Anliegen auf Grundlage der Prompt-Logik genehmigen, blockieren oder kennzeichnen.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-file-path.sh"
          }
        ]
      }
    ]
  }
}

Wann Sie PreToolUse verwenden sollten:

• Blockierung gefährlicher Bash-Befehle wie rm -rf oder force pushes
• Automatische Genehmigung sicherer, sich wiederholender Vorgänge zur Reduzierung von Ermüdung bei Prompts
• Validierung von Dateipfaden vor dem Schreiben, um versehentliches Überschreiben zu vermeiden
• Änderung von Tool-Eingaben zum Einfügen projektspezifischer Standardeinstellungen

PermissionRequest

Dieser Hook wird ausgelöst, wenn Claude normalerweise einen Berechtigungsdialog anzeigen würde. Dieser Hook fängt den Moment ab, bevor Sie eine Bestätigungsaufforderung sehen, sodass Ihr Skript entscheiden kann, ob es zulassen, ablehnen oder den Benutzer trotzdem fragen soll.

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "Bash(npm test*)",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validate-test-command.sh"
          }
        ]
      }
    ]
  }
}

Dieses Beispiel genehmigt automatisch jeden Bash-Befehl, der mit npm test beginnt. Das Matcher-Muster kann Argumente für eine feinere Kontrolle enthalten.

Wann PermissionRequest verwendet werden sollte:

• Automatische Genehmigung von Testbefehlen, die Sie dutzende Male pro Sitzung ausführen
• Blockierung des Schreibzugriffs auf Konfigurationsdateien im Produktivbetrieb
• Zulassen von Lesevorgängen für bestimmte Verzeichnisse ohne Prompts
• Ablehnung jedes Befehls, der einem gefährlichen Muster entspricht

PostToolUse

Wird sofort nach erfolgreichem Abschluss eines Tools ausgelöst. Ihr Skript erhält Informationen darüber, was passiert ist, einschließlich der Tool-Ausgabe, und verwendet Matcher, um zu filtern, welche Tools es auslösen.

Dieses Beispiel von PostToolUse führt Prettier für jede Datei aus, die Claude schreibt oder bearbeitet. Die Pipe-Syntax im Matcher führt dazu, dass sie sowohl für das Schreib- als auch für das Bearbeitungstool ausgelöst wird.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

Wann Sie PostToolUse verwenden sollten:

• Ausführung von Prettier, Black oder gofmt nach jedem Dateischreibvorgang zur Umsetzung der Formatierung
• Protokollierung aller Dateiänderungen in einem Audit-Trail
• Auslösen von Linters und Anzeige von Warnungen nach Codeänderungen
• Senden von Benachrichtigungen bei Abschluss bestimmter Vorgänge

PreCompact

Wird ausgelöst, bevor Claude den Gesprächskontext komprimiert, um Speicherplatz freizugeben. Die Komprimierung fasst ältere Teile des Gesprächs zusammen, sodass einige Details verloren gehen. Dieser Hook gibt Ihnen die Möglichkeit, Informationen zu bewahren, bevor dies geschieht.

Dieses PreCompact-Beispiel sichert das Transkript vor der automatischen Komprimierung. Der Matcher kann „automatisch“ oder „manuell“ sein, sodass Sie zwischen automatischer Komprimierung und benutzerausgelösten Komprimierungsereignissen unterscheiden können.

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/backup-transcript.sh"
          }
        ]
      }
    ]
  }
}

Wann ist PreCompact verwenden sollten:

• Sicherung des vollständigen Transkripts in einer Datei vor der Zusammenfassung
• Extrahieren und Speichern wichtiger Entscheidungen oder Code-Teile
• Protokollierung von Meilensteinen in einer Sitzung zur späteren Überprüfung

SessionStart

Wird ausgelöst, wenn Claude Code eine neue Sitzung startet oder eine vorhandene fortsetzt. Was auch immer Ihr Skript ausgibt, wird dem Konversationskontext hinzugefügt, sodass Claude mit diesen bereits geladenen Informationen beginnt.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git status --short && echo '---' && cat TODO.md"
          }
        ]
      }
    ]
  }
}

Zu Beginn jeder Sitzung kennt Claude Ihren aktuellen Git-Status und die TODO-Liste. Stdout wird automatisch zu Kontext.

Wann Sie SessionStart verwenden sollten:

• Claude wird mit Ihrem aktuellen git-Branch und den letzten Commits versorgt
• Laden der Inhalte Ihrer TODO-Liste oder Ihres Sprint-Backlogs
• Einfügen umgebungsspezifischer Konfigurationsdetails

Anhalten

Wird ausgelöst, wenn Claude fertig geantwortet hat und normalerweise auf Ihre nächste Eingabe warten würde. Ihr Skript kann überprüfen, was Claude erstellt hat, und entscheiden, ob die Aufgabe wirklich abgeschlossen ist.

Das Skript kann JSON mit "continue": true zurückgeben, damit Claude weiterarbeitet, was für Workflows mit mehreren Schritten nützlich ist:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review whether the task is complete. If all requirements are met, respond with 'complete'. If work remains, respond with 'continue' and specify what still needs to be done."
          }
        ]
      }
    ]
  }
}

Wann Sie Stoppen verwenden sollten:

• Claude zwingen, weiterzumachen, bis alle Punkte auf einer Checkliste erledigt sind
• Überprüfen, ob Tests bestanden werden, bevor eine Aufgabe als abgeschlossen betrachtet wird
• Auslösen der Zusammenfassungsgenerierung am Ende einer Sitzung
• Überprüfung der Kompilierung des generierten Codes vor dem Beenden

SubagentStop

Dieser Hook wird immer dann ausgelöst, wenn ein über das Aufgaben-Tool erstellter Subagent seine Aufgabe fertiggestellt hat. Funktioniert genauso wie Stoppen, wird jedoch gezielt ausgelöst, wenn ein Subagent seine Aktion abgeschlossen hat (im Gegensatz zum Hauptagenten). Die Konfiguration von SubagentStop spiegelt die Stop-Hook-Struktur wider:

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate the subagent's output. Verify the task was completed correctly and the results meet quality standards. If the output is satisfactory, respond with 'accept'. If issues exist, respond with 'reject' and explain what needs to be fixed."
          }
        ]
      }
          ]
  }
}

Wann Sie SubagentStop verwenden sollten:

• Überprüfung, ob die Ausgabe des Subagenten die Qualitätskriterien erfüllt
• Auslösung von Folgeaktionen auf der Grundlage der Ergebnisse von Subagenten
• Protokollierung der Aktivitäten von Subagenten für das Debugging oder die Auditierung

UserPromptSubmit

Wird ausgelöst, wenn Sie einen Prompt senden, bevor Claude diesen verarbeitet. Alle Ausgaben Ihres Skripts über stdout werden zusammen mit Ihrem Prompt in den Kontext von Claude eingefügt. Dadurch eignet sich UserPromptSubmit gut zum dynamischen Einfügen von Informationen, die Claude berücksichtigen soll.

In diesem Beispiel erhält Claude jedes Mal, wenn Sie einen Prompt senden, den Inhalt Ihrer Sprint-Kontextdatei. So bleibt Claude über aktuelle Prioritäten auf dem Laufenden, ohne dass Sie diese erneut nennen müssen.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat ./current-sprint-context.md"
          }
        ]
      }
    ]
  }
}

Wann Sie UserPromptSubmit verwenden sollten:

• Einbeziehung des aktuellen Sprint-Kontexts oder Projektprioritäten bei jedem Prompt
• Validierung von Prompts, bevor sie Claude erreichen
• Blockieren bestimmter Anfragetypen basierend auf Inhalten
• Hinzufügen von dynamischem Kontext, z. B. aktuellen Fehlerprotokollen oder Testergebnissen

Konfiguration und Dateispeicherorte

Hooks befinden sich in JSON-Einstellungsdateien auf drei Ebenen. Hooks auf Projektebene werden in .claude/settings.json in Ihrem Repository gespeichert, sodass Sie sie mit Ihrem Team teilen können. Hooks auf Benutzerebene werden in ~/.claude/settings.json gespeichert und gelten für alle Ihre Projekte. Lokale Projekthooks werden in .claude/settings.local.json für persönliche Konfigurationen gespeichert, die Sie nicht committen möchten.

Einstellungen auf Projektebene haben Vorrang vor Einstellungen auf Benutzerebene. Es gibt auch vom Unternehmen verwaltete Richtlinieneinstellungen für die organisatorische Steuerung. Ausführliche Informationen finden Sie in den Claude Code-Einstellungen.

Profitipp: Dies ist dieselbe Datei, in der Sie detaillierte Berechtigungen für Claude-Aktionen auf Projekt-, Benutzer- oder lokaler Ebene festlegen können. Sie können Claude beispielsweise explizit das Lesen aller Dateien in einem Verzeichnis erlauben, damit Sie es nicht jedes Mal genehmigen müssen, oder Änderungen an vertraulichen Dateien blockieren.

Matcher-Syntax

Matcher ermöglichen es Ihnen zu filtern, welche Tools Ihren Hook auslösen können. Sie funktionieren nur bei PreToolUse-, PostToolUse- und PermissionRequest-Hooks.

Das einfache Abgleichen von Zeichenfolgen funktioniert genau so, wie Sie es erwarten: „Schreiben“ passt nur für das Schreib-Tool.

Zum Beispiel:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

Mit der Pipe-Syntax können Sie mehrere Tools abgleichen: „Schreiben|Bearbeiten“ wird entweder ausgelöst, wenn Platzhalter mit allen Tools übereinstimmen: „*“ oder eine leere Zeichenfolge stimmen allen Tools zu.

Hinweis: Matcher unterscheiden zwischen Groß- und Kleinschreibung, daher wird „bash“ nicht dem Bash-Tool zugeordnet.

Zur feineren Steuerung können Argumentationsmuster wie „Bash(npm test*)“ bestimmten Befehlsargumenten entsprechen. MCP-Tool-Patterns folgen dem Format „mcp__memory__.*“ für Model Context Protocol-Tools.

Eingabe, Ausgabe und strukturierte Antworten

Was Hooks erhalten

Alle Hooks erhalten JSON über stdin mit Sitzungsinformationen und ereignisspezifischen Daten. Gängige Felder sind: session_id, transcript_path, cwd, permission_mode und hook_event_name.

Darüber hinaus erhalten tool-bezogene Hooks auch tool_name und tool_input. Auf Grundlage dieser Daten können Ihre Skripte fundierte Entscheidungen über die Reaktion treffen.

Wie Hooks reagieren

Ausgangscodes bestimmen das Grundergebnis. Der Exit-Code 0 bedeutet Erfolg, und stdout wird entweder für JSON verarbeitet oder dem Kontext hinzugefügt. Exit-Code 2 bedeutet einen blockierenden Fehler: stderr wird zur Fehlermeldung und die Aktion wird verhindert.

Andere Exit-Codes weisen auf nicht blockierende Fehler hin, wobei stderr im Verbose-Modus angezeigt wird.

Über Exit-Codes hinaus können Hooks für mehr Kontrolle strukturiertes JSON zurückgeben. Zu den Feldern gehören: decision (approve, block, allow oder deny), reason (Erklärung, die Claude angezeigt wird), continue (damit Stop-Hooks die Fortsetzung erzwingen) und updatedInput (zur Änderung von Toolparametern vor der Ausführung).

Umgebung und Ausführung

Hooks haben Zugriff auf Umgebungsvariablen, z. B.: CLAUDE_PROJECT_DIR für den Projekt-Stammpfad, CLAUDE_CODE_REMOTE, das in Webumgebungen auf true gesetzt ist, und CLAUDE_ENV_FILE für SessionStart-Hooks, um Variablen zu persistieren. Sie können auch auf Standard-Umgebungsvariablen von Ihrer Shell zugreifen.

Außerdem ist für Hooks ein Standard-Timeout von 60 Sekunden festgelegt, das pro Hook konfiguriert werden kann. Wenn mehrere Hooks mit einem Ereignis übereinstimmen, werden sie parallel ausgeführt. Identische Befehle werden automatisch entfernt.

Sicherheitsaspekte

Hooks führen beliebige Shell-Befehle mit Ihren Benutzerberechtigungen aus. Claude Code bietet eine Sicherheitsmaßnahme: Direkte Änderungen an Hook-Konfigurationsdateien müssen im Menü /hooks überprüft werden, bevor sie wirksam werden. So kann verhindert werden, dass bösartiger Code Ihrer Konfiguration unbemerkt Hooks hinzufügt.

Wenn Sie Hooks jedoch konfigurieren und genehmigen, werden sie mit Ihren Berechtigungsstufen ausgeführt.

Profitipp: Bedenken Sie die Risiken, bevor Sie Befehle in einer Umgebung ausführen. Wenn Sie Befehle mit Hooks ausführen möchten, sollten Sie bewährte Praktiken in Betracht ziehen, z. B.: Validierung und Bereinigung von Eingaben aus stdin, Zitieren von Shell-Variablen, um Injektionen zu vermeiden, die Verwendung absoluter Pfade für Skripte und die Vermeidung der Verarbeitung vertraulicher Dateien wie .env oder Anmeldeinformationen.

Debugging und Tests

Claude Code protokolliert alles in Transkriptdateien und bietet somit einen Überblick über Toolaufrufe und -antworten, ohne dass dies separat eingerichtet werden muss. Jeder Hook erhält ein Feld transcript_path, das auf eine JSONL-Datei mit dem vollständigen Sitzungsverlauf verweist. Sie können einen SessionStart-Hook verwenden, um zu protokollieren, wo sich jedes Transkript befindet:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"Session: \" + .transcript_path' >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

Dann können Sie das Transkript verfolgen, um Claude in Echtzeit bei der Arbeit zu beobachten: tail -f /path/to/transcript.jsonl | jq .

Hook-spezifisches Debugging

Fügen Sie für Hook-spezifisches Debugging Ihren Hook-Skripten eine Protokollierung hinzu. Die Transkriptdateien zeigen an, was Claude getan hat, aber nicht, warum Ihr Hook etwas genehmigt oder blockiert hat.

Mit ein wenig zusätzlichem Aufwand können Sie ein kleines Bash-Skript hinzufügen, das Ihre Tools wrappt und die zusätzlichen Informationen protokolliert. Zum Beispiel log-wrapper.sh:

#!/bin/bash
LOG=~/.claude/hooks.log
INPUT=$(cat)

TOOL=$(echo "$INPUT" |
 jq -r '.tool_name // "n/a"')
EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "n/a"')

echo "=== $(date) | $EVENT | $TOOL ===" >> "$LOG"

echo "$INPUT" | "$1"
CODE=$?

echo "Exit: $CODE" >> "$LOG"
exit $CODE

Dieses kleine Wrapper-Skript erfasst stdin in einer Variablen, protokolliert den Zeitstempel und den Tool-Namen und leitet die Eingabe dann an Ihr tatsächliches Tool weiter.

Sobald Sie log-wrapper.sh geschrieben haben, würden Sie es dann dem Tool-Aufruf im Hook voranstellen:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "log-wrapper.sh your-tool-command.py"
          }
        ]
      }
    ]
  }
}

Profitipp: Weitere Tipps zum Debugging finden Sie in der Debugging-Dokumentation von Claude Code.

Erstellen Sie Ihre eigenen Hooks

Beginnen Sie mit einem einfachen Hook, der ein Problem in Ihrem Workflow löst. Der Formatierungshook von PostToolUse ist ein guter Anfang, da das Feedback sofort und sichtbar ist. Sobald dies funktioniert, erweitern Sie auf Basis dessen, was Sie gelernt haben.

Eine vollständige Referenzdokumentation, einschließlich aller verfügbaren Felder und erweiterten Muster, finden Sie in der offiziellen Hooks-Dokumentation.

Mit Hooks können Sie Claude Code an Ihren Workflow anpassen, anstatt Ihren Workflow an das Tool anzupassen. Wenn Sie in die Konfiguration von Hooks investieren, zahlt sich das in jeder Sitzung aus.

Passen Sie Ihre Claude Code-Workflows noch heute mit Hooks an.