Workban

Ratgeber · Claude Code

Claude Code Hooks: Befehle, die jedes Mal laufen.

Eine Anweisung in CLAUDE.md ist eine Bitte an das Modell. Ein Hook ist ein Befehl, den Claude Code an einer festen Stelle selbst ausführt, jedes Mal. Diese Anleitung erklärt Ereignisse, Matcher und Exit-Codes, zeigt einen Hook, der Änderungen an .env-Dateien sperrt, und wie Workban Hooks nutzt.

  • Claude Code
  • Mit Beispiel
  • Auch für Codex
  • Stand 30. Oktober 2026

Grundlagen

Was ein Hook ist.

Ein Hook ist ein Befehl, den Claude Code bei einem bestimmten Ereignis startet: bevor ein Werkzeug läuft, nachdem es gelaufen ist, wenn eine Sitzung beginnt oder wenn Claude mit seiner Antwort fertig ist. Er bekommt die Einzelheiten des Ereignisses als JSON auf der Standardeingabe, etwa den Namen des Werkzeugs und seine Parameter.

Zurück antwortet der Hook über seinen Exit-Code und seine Ausgabe. So kann er eine Aktion erlauben, sperren, eine Rückfrage auslösen oder Claude zusätzlichen Kontext geben. Weil der Hook außerhalb des Modells läuft, gilt er auch dann, wenn Claude eine Anweisung übersieht.

Orte

Wo Hooks stehen.

Hooks stehen in den JSON-Einstellungen von Claude Code. Der Ort bestimmt, wofür sie gelten. Einträge mehrerer Orte ergänzen sich, statt sich zu ersetzen.

~/.claude/settings.json
Für alle deine Projekte, nur auf deinem Rechner.
.claude/settings.json
Für ein Projekt. Liegt im Repository, gilt also für alle, die es klonen.
.claude/settings.local.json
Für ein Projekt, nur für dich, nicht im Repository.
Plugins, Skills, Subagenten
Ein Plugin bringt Hooks mit, solange es eingeschaltet ist. Skills und Subagenten können Hooks in ihrem Kopf definieren.
Verwaltete Einstellungen
Für eine ganze Organisation, von Admins vorgegeben.

Ereignisse

Die Ereignisse, die du am häufigsten brauchst.

Die Referenz von Claude Code nennt über 30 Ereignisse. Diese tragen die meisten Hooks.

SessionStart
Beim Start oder Fortsetzen einer Sitzung. Was der Hook als Text ausgibt, liest Claude als Kontext.
UserPromptSubmit
Bevor Claude deine Eingabe bearbeitet. Kann Kontext ergänzen oder die Eingabe ablehnen.
PreToolUse
Vor jedem Werkzeugaufruf. Kann ihn sperren, erlauben oder eine Rückfrage auslösen.
PostToolUse
Nachdem ein Werkzeug erfolgreich gelaufen ist, etwa für Formatierer oder Prüfungen.
Stop
Wenn Claude mit seiner Antwort fertig ist. Nicht nach einer Unterbrechung durch dich.
SubagentStop
Wenn ein Subagent fertig ist.
SessionEnd
Wenn die Sitzung endet.

Steuerung

Matcher grenzen ein, Exit-Codes entscheiden.

Ein Matcher legt fest, wann ein Hook überhaupt startet. Sein Exit-Code sagt Claude Code, was dann passiert.

Matcher
Bei Werkzeug-Ereignissen der Name des Werkzeugs: Bash, Edit|Write für beide, mcp__.* als regulärer Ausdruck für alle MCP-Werkzeuge. Leer oder * heißt immer.
Exit 0
Alles in Ordnung. Gibt der Hook ein JSON-Objekt aus, wendet Claude Code dessen Felder an.
Exit 2
Sperrt die Aktion, bei Ereignissen, die sperren können. Was der Hook auf stderr schreibt, bekommt Claude als Grund.
Anderer Exit-Code
Ein Fehler, der nichts sperrt: Die Aktion läuft weiter, Claude Code zeigt einen Hinweis.
permissionDecision
Feiner per JSON bei PreToolUse: allow überspringt die Rückfrage, deny sperrt, ask fragt dich.

Beispiel

Keine Änderungen an .env-Dateien.

Ein PreToolUse-Hook für die Werkzeuge Edit und Write, eingetragen in deinen Benutzer-Einstellungen.

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/protect-env.sh" }
        ]
      }
    ]
  }
}

Beispiel

Das Skript dazu sperrt mit Exit-Code 2.

Es liest den Dateipfad aus der Eingabe. Ist es eine .env-Datei, etwa .env oder .env.local, schreibt es den Grund auf stderr und endet mit 2.

~/.claude/hooks/protect-env.sh
#!/bin/bash
# Keine Änderungen an .env-Dateien
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.env|*.env.*)
    echo "Keine Änderungen an $file" >&2
    exit 2
    ;;
esac
exit 0

Das Skript braucht jq und muss ausführbar sein (chmod +x). Mit /hooks siehst du in Claude Code alle eingerichteten Hooks und woher sie kommen. Mit claude --debug schreibt Claude Code ins Debug-Log unter ~/.claude/debug, welche Hooks gelaufen sind und mit welchem Ergebnis.

In Workban

So nutzt Workban die Hooks.

workban setup trägt einen einzigen Befehl, workban hook run, für die Ereignisse ein, die Workban braucht. In Repositorys ohne .workban.toml tut er nichts.

SessionStart
Zeigt, was läuft und was im Backlog liegt, und hält CLI, Regel und Skill aktuell.
PreToolUse
Der Riegel: hält Änderungen im Repository an, solange die Sitzung keine eigene Aufgabe gestartet hat. Vor einer Websuche erinnert er ans Wissen des Teams.
PostToolUse
Welches Werkzeug die Sitzung gerade nutzt, für die Seite Live.
UserPromptSubmit, PermissionRequest
Die Phase auf der Karte: ob der Agent arbeitet oder auf dich wartet.
Stop
Der Token-Verbrauch der Runde, gelesen aus dem Protokoll der Sitzung.
SessionEnd, SubagentStop
Wann eine Sitzung oder ein Subagent fertig ist.

Codex

Codex hat eigene Hooks, mit einer Freigabe.

Codex kennt Hooks nach demselben Muster: Ereignis, Matcher, Befehl, darunter SessionStart, PreToolUse, PostToolUse und Stop. Sie stehen in einer hooks.json oder als [hooks] in der config.toml.

Der wichtigste Unterschied: Codex führt einen Hook erst aus, wenn du ihn über /hooks geprüft und freigegeben hast. Ändert sich der Hook, fragt Codex neu.

Fragen

Was oft gefragt wird.

Hook oder Anweisung in CLAUDE.md?
Beides hat seinen Platz. Eine Anweisung erklärt einen Ablauf und warum er so ist, das Modell folgt ihr meistens. Ein Hook läuft jedes Mal. Was immer gelten muss, etwa eine Sperre, gehört in einen Hook. Workban nutzt beides: eine Regel für den Ablauf, Hooks für Riegel und Messung.
Sind Hooks ein Risiko?
Ein Hook läuft mit deinen Rechten und kann alles, was dein Benutzerkonto kann. Lies jeden Hook, bevor du ihn einträgst, besonders aus fremden Repositorys. In einer interaktiven Sitzung führt Claude Code Hooks erst aus, wenn du dem Ordner vertraust.
Warum startet mein Hook nicht?
Meist passt der Matcher nicht, das Skript ist nicht ausführbar oder es gibt ungültiges JSON aus. /hooks zeigt, ob Claude Code den Hook kennt, das Debug-Log von claude --debug, ob er lief und was er zurückgab.

Quellen

Woher die Angaben stammen.

Was hier über andere Produkte steht, stammt aus deren eigenen Seiten und Ankündigungen, Stand siehe oben. Funktionen und Pläne ändern sich, im Zweifel gilt die Quelle.

Weiter

Wie Workban mit Claude Code und Codex arbeitet.

Loslegen

Probier es mit deiner nächsten Aufgabe.

Workban ist kostenlos. Dein Workspace steht in einer Minute, und die erste Aufgabe erscheint, sobald dein Agent loslegt.