Claude Code Hooks: Wiederkehrende Aktionen automatisieren

Stell dir vor, du hättest einen unsichtbaren Assistenten, der immer genau dann eingreift, wenn etwas Bestimmtes passiert: Immer wenn du eine Datei speicherst, formatiert er deinen Code sauber. Immer wenn dein KI-Helfer einen riskanten Befehl ausführen will, hält er kurz inne und fragt nach. Genau das machen Claude Code Hooks. Ein Hook (englisch für „Haken“) ist ein automatischer Auslöser nach dem Prinzip „immer wenn X passiert, mach Y“. In diesem Artikel zeige ich dir, was Hooks in Claude Code sind, welche es gibt und wie du sie in wenigen Minuten einrichtest, ohne dass du dafür ein Profi-Entwickler sein musst. Solltest du Claude Code noch nicht installiert haben, fang am besten mit der Claude Code Anleitung an.

Was sind Hooks in Claude Code?

Claude Code Hooks sind kleine Regeln, die automatisch einen Befehl ausführen, sobald ein bestimmtes Ereignis eintritt. Ein „Ereignis“ (auf Englisch: Event) ist einfach ein Moment im Ablauf, zum Beispiel „eine Datei wurde gerade geändert“ oder „die Arbeitssitzung ist zu Ende“. Du legst einmal fest: „Wenn dieses Ereignis passiert, führe diesen Befehl aus“ und ab dann kümmert sich Claude Code von ganz allein darum.

Das Schöne daran: Du musst nicht mehr daran denken. Wiederkehrende Handgriffe, die du sonst nach jeder Änderung manuell machen würdest, passieren jetzt im Hintergrund. Das spart Zeit, sorgt für Konsistenz und nimmt dir das Gefühl, ständig irgendetwas zu vergessen. Gerade für Solopreneure, die alles allein stemmen, ist das Gold wert.

Warum ein Hook mehr ist als eine Bitte an die KI

Ein wichtiger Unterschied: Hooks sind keine Bitte an die KI („formatiere doch bitte den Code“), sondern eine feste Anweisung an das Programm selbst. Technisch gesagt: Hooks laufen außerhalb des Modell-Kontexts. Claude sieht sie gar nicht als Text, den es interpretieren könnte, sondern spürt nur das Ergebnis. Es kann sie deshalb nicht überreden, nicht umgehen und nicht vergessen.

Ich vergleiche das gern mit einer Brandschutztür. Ein Schild „Bitte nicht rauchen“ ist ein netter Hinweis. Die Brandschutztür fragt nicht, sie schließt einfach. Genau das ist der Unterschied zwischen einem Satz in deiner CLAUDE.md und einem Hook. Die offizielle Dokumentation nennt das deterministisches Enforcement – ein sperriges Wort für eine einfache Sache: Es passiert. Jedes Mal. Egal, was das Modell gerade denkt.

Und noch ein hübscher Nebeneffekt: Weil Hooks außerhalb des Modells laufen, kosten sie dich null Tokens. Eine Regel in der CLAUDE.md wird bei jedem Turn mitgeschleppt und frisst Kontext. Ein Hook nicht. Du bekommst also mehr Verlässlichkeit und zahlst weniger dafür. Klingt nach einem guten Deal, oder?

Welche Events gibt es?

Damit ein Hook weiß, wann er loslegen soll, knüpft er sich an ein bestimmtes Event. Inzwischen sind das über 30 Stück – von „Session gestartet“ über „Berechtigung angefragt“ bis „Arbeitsverzeichnis gewechselt“. Keine Sorge, du musst die nicht alle kennen. Ich zeige dir zuerst die drei, mit denen du 90 Prozent aller sinnvollen Automatisierungen abdeckst.

Die drei Klassiker

• PreToolUse – wird ausgelöst, bevor Claude Code ein Werkzeug (ein „Tool“, also zum Beispiel das Schreiben einer Datei oder das Ausführen eines Befehls) benutzt. Praktisch, um vorher zu prüfen oder etwas zu blockieren.
• PostToolUse – wird ausgelöst, nachdem ein Tool benutzt wurde, also zum Beispiel nach einer Datei-Änderung. Ideal, um danach automatisch aufzuräumen oder zu formatieren.
• Stop – wird ausgelöst, wenn Claude Code mit seiner Antwort fertig ist, also am Ende einer Aufgabe. Gut für Benachrichtigungen oder Abschluss-Checks.

Merk dir einfach die Logik: Pre = davor, Post = danach, Stop = am Ende. Damit hast du das Grundgerüst im Kopf.

Die spannenden Nachzügler

Seit dem Original-Stand dieses Artikels ist einiges dazugekommen, und ein paar dieser Events sind richtig nützlich. SessionStart feuert, wenn eine Sitzung beginnt – perfekt, um Claude automatisch Projektkontext mitzugeben. SessionEnd ist das Gegenstück am Schluss, gut für Aufräumarbeiten oder ein Log.

PreCompact springt an, bevor Claude Code seinen Kontext zusammenstaucht (das „Compacting“, wenn das Fenster voll wird). Damit sicherst du dir das Transkript, bevor Details verschwinden – und seit Version 2.1.105 kann dieser Hook sogar blocken. PostToolBatch läuft, nachdem ein ganzer Schwung Tool-Aufrufe durch ist, statt nach jedem einzelnen. Das schont die Nerven, wenn dein Formatter sonst zwanzigmal hintereinander anspringt.

Dazu kommen PermissionRequest (feuert, wenn Claude nach einer Erlaubnis fragt – damit kannst du harmlose Dinge automatisch durchwinken), SubagentStop für Subagenten und Notification für Meldungen. Letzteres kennt seit Version 2.1.198 auch die Typen agent_needs_input und agent_completed, was für Background-Agents Gold wert ist. Die vollständige Liste findest du in der Hooks-Referenz.

Wichtig zu wissen: Nicht jedes Event kann etwas blockieren. PreToolUse, UserPromptSubmit, Stop, PostToolBatch und PermissionRequest können es. SessionStart, PostToolUse oder Notification dagegen nicht – die dürfen nur zuschauen und melden. Merk dir das, bevor du dich wunderst, warum dein Sicherheits-Hook nichts stoppt.

Wie richtest du einen Hook ein?

Hooks werden in einer Konfigurationsdatei eingetragen: der settings.json. Das ist eine schlichte Textdatei im sogenannten JSON-Format. JSON ist einfach eine geordnete Schreibweise für Einstellungen, mit geschweiften Klammern und Anführungszeichen, die der Computer gut lesen kann. Du findest die Datei in deinem Projekt unter .claude/settings.json.

Du musst die Datei aber gar nicht von Hand bearbeiten, wenn du nicht willst. Claude Code bringt einen eingebauten Slash-Command mit: Tippe einfach /hooks in den Chat, und du wirst Schritt für Schritt durch die Einrichtung geführt. Ein „Slash-Command“ ist ein Kurzbefehl, der mit einem Schrägstrich beginnt.

So sieht ein einfacher Hook aus, der nach jeder Datei-Änderung deinen Code automatisch formatiert. Das Formatieren übernimmt hier ein sogenannter „Formatter“ namens Prettier, der Einrückungen und Abstände sauber macht:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ]
  }
}

Was passiert hier? Unter PostToolUse (also „nachdem ein Tool benutzt wurde“) sagt der matcher: „Reagiere nur, wenn das Tool Edit oder Write war“, also wenn eine Datei bearbeitet oder neu geschrieben wurde. Dann führt der command den Formatier-Befehl aus. Mehr ist es nicht. Ein klares „Wenn das passiert, mach das“.

Wo die Datei liegt – und wer gewinnt

Es gibt mehrere Orte für deine Hooks, und die haben eine feste Rangfolge. Von unten nach oben:

• ~/.claude/settings.json – gilt für alle deine Projekte, bleibt lokal bei dir. Niedrigste Priorität.
• .claude/settings.local.json – projektbezogen, aber gitignored. Deine private Spielwiese.
• .claude/settings.json – projektbezogen und teilbar über Git. Hier gehören Team-Regeln rein.
• Managed Policy Settings – firmenweit vorgegeben, höchste Priorität. Mit allowManagedHooksOnly kann eine IT-Abteilung alle privaten Hooks komplett aussperren.

Meine Empfehlung aus der Praxis: Alles, was das ganze Team betrifft (Formatter, Secret-Schutz), kommt in die versionierte .claude/settings.json. Alles, was nur dein persönlicher Komfort ist (Sounds, Notifications), in die globale Datei in deinem Benutzerverzeichnis. Damit fährst du am saubersten.

Die fünf Handler-Typen

Ein Hook muss nicht zwingend ein Shell-Befehl sein. Inzwischen gibt es fünf Typen, und der Unterschied ist wichtiger, als er klingt:

• command – der Klassiker. Ein Shell-Befehl oder Script. Bekommt JSON über stdin, antwortet über Exit-Codes. Damit machst du 90 Prozent von allem.
• http – schickt einen POST an eine URL. Praktisch für zentrales Logging oder Slack. Achtung, klassische Falle: Ein HTTP-Hook kann nicht über den Statuscode blocken. Du musst mit 2xx antworten und im Body {"decision":"block"} mitschicken.
• mcp_tool – ruft ein Tool auf einem verbundenen MCP-Server auf. Praktisch, wenn du dir dort schon Logik gebaut hast.
• prompt – lässt ein Claude-Modell entscheiden. Antwortet mit {"ok":true} oder {"ok":false,"reason":"..."}. Nur bei PreToolUse, PostToolUse und PermissionRequest möglich.
• agent – ein kleiner Subagent mit Lese-Rechten prüft tiefer nach. Gründlich, aber langsam.

Klingt nach viel Auswahl? Ist es. Aber ehrlich: Fang mit command an. Alles andere ist am Anfang wie mit Kanonen auf Spatzen zu schießen.

Matcher und das if-Feld

Der matcher entscheidet, wann dein Hook überhaupt reagiert. Lässt du ihn weg oder schreibst "*", feuert er immer. Schreibst du "Edit|Write", nur bei diesen beiden Tools. Und hier lauern zwei Stolpersteine, in die ich selbst reingelaufen bin: Keine Leerzeichen um den senkrechten Strich! "Edit | Write" funktioniert nicht, "Edit|Write" schon. Und alles ist case-sensitive – bash greift nicht, Bash schon.

Für MCP-Tools nutzt du das Schema mcp__server__tool, ein .* am Ende matcht alle. Und seit Version 2.1.85 gibt es das if-Feld, mit dem du noch feiner filterst – etwa "if": "Bash(git *)", damit dein Hook nur bei Git-Befehlen anspringt. Das ist deutlich eleganter, als im Script selbst herumzuprüfen.

Exit-Codes: die Sprache deines Hooks

Dein Hook redet mit Claude Code über sogenannte Exit-Codes. Das sind Zahlen, die ein Script beim Beenden zurückgibt. Drei Fälle musst du kennen:

• 0 = alles gut. Was du auf stdout ausgibst, wird als JSON gelesen und verarbeitet.
• 2 = blockierender Fehler. Was auf stderr steht, geht an Claude, die Aktion wird gestoppt. Nur bei block-fähigen Events.
• alles andere = nicht-blockierender Fehler. Du bekommst eine Meldung, aber es läuft weiter.

Ganz wichtig: JSON auf stdout wird nur bei Exit 0 ausgewertet. Wenn du also exit 2 machst und dabei schönes JSON ausgibst, wird das ignoriert – dann zählt nur stderr. Das ist einer der häufigsten Anfängerfehler.

Mit JSON-Output kannst du übrigens erstaunlich viel: Bei PreToolUse setzt du permissionDecision auf allow, deny, ask oder defer – und mit updatedInput änderst du die Tool-Argumente sogar noch vor der Ausführung. Bei PostToolUse kannst du seit v2.1.121 mit updatedToolOutput die Ausgabe umschreiben, bevor Claude sie sieht.

Nützliche Hook-Ideen für den Alltag

Sobald du das Prinzip verstanden hast, öffnet sich eine ganze Werkzeugkiste. Hier ein paar Ideen, die sich im Alltag richtig auszahlen – mit den Events, die du dafür brauchst.

Gefährliche Befehle blocken

Mein Lieblings-Hook, und der, mit dem ich die besten Erfahrungen gemacht habe. Ein kleines Script prüft jeden Bash-Befehl, bevor er läuft. Findet es rm -rf oder einen Force-Push auf main, beendet es sich mit exit 2 und die Sache ist gestorben:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-bash.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Dasselbe Prinzip nutzt du für den Secret-Schutz: Dein Script schaut, ob der Pfad auf .env, .git/ oder eine package-lock.json zeigt, und blockt. So landet kein API-Key aus Versehen im Repository. Ein echter Schutz vor peinlichen Pannen.

Kontext beim Start injizieren

Kennst du das, wenn Claude in einer neuen Session erstmal wieder alles vergessen hat? Dafür gibt es SessionStart. Was dein Hook auf stdout ausgibt, bekommt Claude als Kontext serviert:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "cat ~/.claude/project-context.md"
          }
        ]
      }
    ]
  }
}

Logging, das nicht bremst

Seit Anfang 2026 gibt es async Hooks. Mit "async": true läuft dein Hook im Hintergrund und hält nichts auf. Perfekt für Logging, Backups und Benachrichtigungen. Aber Achtung: Ein async-Hook kann niemals exit 2 machen. Für Sicherheits-Blocking ist er also tabu.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-log.txt",
            "async": true
          }
        ]
      }
    ]
  }
}

Weitere Klassiker

• Auto-Format: Wie oben gezeigt. Nach jeder Änderung läuft ein Formatter oder ein „Linter“ (ein Programm, das deinen Code auf Fehler und unsauberen Stil prüft). Mehrere Hooks in einer Gruppe laufen parallel – Prettier und ESLint gleichzeitig sind also kein Problem.
• Tests erzwingen: Ein Stop-Hook, der deine Tests laufen lässt und mit exit 2 abbricht, wenn sie rot sind. Claude arbeitet dann einfach weiter. Prüfe dabei unbedingt das Feld stop_hook_active, sonst baust du dir eine Endlosschleife!
• Transcript-Backup: Ein PreCompact-Hook mit async, der dein Transkript wegkopiert, bevor Kontext zusammengestaucht wird.
• Benachrichtigung: Ein Notification- oder Stop-Hook, der dir Bescheid gibt, wenn Claude fertig ist. So musst du nicht auf den Bildschirm starren.
• Auto-Approve: Ein PermissionRequest-Hook, der harmlose Dinge wie Read, Glob und Grep automatisch durchwinkt. Feuert allerdings nicht im -p-Modus – dort brauchst du PreToolUse.

Du siehst: Die meisten Hooks lösen genau die kleinen Nervereien, die sich über den Tag summieren. Einmal eingerichtet, arbeiten sie für dich.

Hooks vs. CLAUDE.md vs. Skills vs. Subagenten

Claude Code hat mittlerweile mehrere Werkzeuge, mit denen du Verhalten steuern kannst. Die Frage „Was gehört wohin?“ ist deshalb berechtigt. Hier meine Faustregel:

• CLAUDE.md – wird bei jedem Turn geladen, kostet also dauerhaft Tokens. Gut für Fakten und Constraints, die immer gelten. Aber: nur ein Ratschlag.
• Skills – nur der Name liegt am Start im Kontext (rund 100 Tokens), der Rest wird bei Bedarf nachgeladen. Ideal für Playbooks on demand. Ebenfalls: nur ein Ratschlag.
• Hooks – laufen beim Event, kosten null Model-Tokens, werden vom Harness ausgeführt. Verbindlich.
• Subagenten – eigener, isolierter Kontext. Kosten rund 20k Tokens Overhead pro Start, dafür bekommst du Parallelität und saubere Trennung.

In der Praxis kombinierst du das am besten: In der CLAUDE.md steht „wir nutzen Prettier“ – damit Claude den Kontext versteht. Der PostToolUse-Hook führt Prettier dann tatsächlich aus. Der eine erklärt, der andere erzwingt. Zusammen sind sie stark.

Sicherheit: Hooks führen echte Befehle aus

Ein ehrliches Wort zur Vorsicht: Hooks sind mächtig, weil sie echte Befehle auf deinem Computer ausführen, und zwar automatisch und ohne erneute Nachfrage. Sie laufen mit deinen vollen Benutzerrechten und es gibt keine Sandbox. Das ist genau ihr Vorteil, aber auch der Punkt, an dem du aufpassen musst.

Dass das kein theoretisches Risiko ist, zeigt die Vergangenheit. In Claude Code wurden mehrere Schwachstellen entdeckt und gepatcht, unter anderem ein Path-Restriction-Bypass (CVE-2025-54794), eine Command Injection (CVE-2025-54795) und ein WebSocket-Auth-Bypass mit möglicher Remote-Code-Ausführung (CVE-2025-52882). Alle sind längst behoben – aber sie zeigen, in welcher Liga du hier spielst. Halte dein Claude Code also aktuell.

Meine Regeln für sichere Hooks

• Trage nur Befehle ein, die du selbst verstehst und denen du vertraust. Wenn du nicht weißt, was ein Befehl tut, baue ihn nicht ein.
• Sei besonders vorsichtig mit Hook-Konfigurationen aus fremden Quellen. Lies sie durch, bevor du sie übernimmst.
• Quote deine Variablen! Immer "$FILE_PATH" statt $FILE_PATH. Ein Leerzeichen im Pfad reicht sonst für Chaos.
• Nutze absolute Pfade über "$CLAUDE_PROJECT_DIR" statt relativer Angaben.
• Sei fail-open: Wenn dein Script den Input nicht parsen kann, beende mit exit 0 statt blind zu blocken.
• Teste jeden Hook, bevor er scharfgeschaltet wird: JSON per echo ins Script pipen und mit $? den Exit-Code prüfen. Und wenn nichts feuert: claude --debug hilft.

Die gute Nachricht: Solange du nur harmlose Dinge wie Formatieren, Testen oder Benachrichtigen einrichtest, bist du auf der sicheren Seite. Behandle deine settings.json einfach mit demselben gesunden Misstrauen, mit dem du auch keine wildfremden Skripte aus dem Internet blind ausführen würdest.

Fazit

Claude Code Hooks sind eine der unterschätztesten Funktionen für alle, die effizienter arbeiten wollen. Statt wiederkehrende Handgriffe immer wieder selbst zu machen, legst du einmal eine Regel nach dem Muster „immer wenn X passiert, mach Y“ fest und überlässt den Rest dem Programm. Ob automatisches Formatieren, das Blocken von Secrets, das Anstoßen von Tests oder eine kleine Benachrichtigung am Ende, die Events PreToolUse, PostToolUse und Stop decken die wichtigsten Fälle ab.

Ja, es gibt inzwischen über 30 Events, fünf Handler-Typen und ein ganzes JSON-Protokoll dahinter. Klingt ganz schön kompliziert? Das muss aber gar nicht sein! Fang mit einem einzigen, harmlosen Hook an, zum Beispiel dem Auto-Format, und taste dich von dort aus weiter. Wenn du eine WordPress-Seite baust, wäre mein Fahrplan: erst PostToolUse mit dem PHP CS Fixer, dann PreToolUse für den .env-Schutz, dann SessionStart für den Projektkontext. Drei Hooks, ein entspannterer Alltag.

Du wirst schnell merken, wie viel ruhiger sich dein Workflow anfühlt, wenn die Routine im Hintergrund einfach läuft. Und ehrlich – wer einmal einen Force-Push auf main durch einen Hook verhindert bekommen hat, will nie wieder ohne arbeiten.

Noch mehr aus KI holen: Sechs fertige Bausteine zum Kopieren gibt es in meinem kostenlosen Werkzeugkasten. Und wer es gründlich angehen will, ist im KI Business Dojo richtig — dort liegen alle Kurse zusammen mit der Community.

Häufige Fragen zu Claude Code Hooks