Claude Code Setup-Hooks

Die Qualität eines Engineering-Teams zeigt sich in einer Zahl: wie lange es dauert, bis ein neuer Mitarbeiter das Projekt auf seinem Rechner zum Laufen bringt.

Gute Teams brauchen einen Link, ein Dokument, ein paar Befehle. Die meisten Teams verlieren ein oder zwei Tage mit Pair-Programming, Slack-Threads, verstaubten Wiki-Seiten und dem Hin und Her, warum etwas kaputt ist.

Agenten machen das lösbar.

Eine Codebasis aufzusetzen war immer eine Wahl zwischen drei schlechten Formen:

Reine Skripte sind vorhersehbar, aber fragil. Sie führen jedes Mal dieselben Befehle aus und stecken fest, sobald sich die Realität verschiebt. Eine fehlende Abhängigkeit oder eine ausgefallene Datenbank, und das Skript stirbt einfach.

Reine Agenten sind clever, aber unzuverlässig. Du kannst keinen in eine CI/CD-Pipeline stecken und erwarten, dass er bei jedem Durchlauf exakt dieselbe Ausgabe liefert.

Reine Docs sind flexibel, aber auf Menschen angewiesen. Niemand liest sie, und nach ein paar Wochen sind sie veraltet.

Was funktioniert, ist alle drei miteinander zu verweben. Skripte übernehmen die Ausführung. Agenten beobachten sie. Du bekommst ein lebendes Dokument, das sich ausführt.

Setup-Hooks kamen am 25. Januar 2026 in Claude Code. Sie sind ein dedizierter Hook-Typ, der vor dem Start deiner Sitzung auslöst. Wenn du ausführst:

claude --init

Geht zuerst der Setup-Hook, dann startet Claude. Der Hook kann Pakete installieren, die Datenbank befüllen und deine Umgebung vorbereiten. Wenn Claude startet, weiß er bereits, was passiert ist.

Hier wird es interessant. Du kannst einen Prompt an das Init-Flag anhängen:

claude --init "/install"

Jetzt läuft der Hook, und der /install-Befehl feuert direkt danach. Der Agent liest die Log-Dateien, arbeitet aus, was passiert ist, und berichtet auf Klartext zurück.

claude --init "/install true"

Drei Setups ergeben sich daraus:

┌─────────────────────────────────────────────────────────┐
│  DETERMINISTISCH       AGENTISCH          INTERAKTIV    │
│  (nur Hooks)           (Hooks + Prompt)   (Hooks + Fragen)│
│                                                         │
│  claude --init          /install          /install true │
│                                                         │
│  - Schnell              - Überwacht       - Stellt Fragen│
│  - Vorhersehbar         - Diagnostiziert  - Passt sich  │
│  - CI-freundlich        - Meldet Status     an           │
└─────────────────────────────────────────────────────────┘

Deterministischer Modus: Nur Skript. Schnell, wiederholbar, perfekt für CI/CD wo jeder Durchlauf übereinstimmen muss.

Agentischer Modus: Erst Skript, dann liest ein Agent die Ergebnisse. Er scannt Log-Dateien, parst Fehler und sagt dir auf Klartext, was gut oder schlecht gelaufen ist.

Interaktiver Modus: Erst Skript, dann zieht der Agent dich in ein kurzes Q&A. "Neue Datenbank oder die alte behalten? Vollinstallation oder minimal? Soll ich zuerst die Voraussetzungen prüfen?"

Das Skript ist immer die Quelle der Wahrheit. Hooks und Prompts rufen dasselbe Skript jedes Mal auf. Was sich ändert, ist ob ein Agent überwacht und ob er dir vorher Fragen stellt.

Just ist ein kleiner Command-Runner, und er passt gut zu Setup-Hooks. Behandle ihn als Startrampe für deine Engineering-Arbeit. Statt Flags auswendig zu lernen, tippst du just und siehst alle verfügbaren Befehle:

just          # See all commands
just cldi     # Deterministic setup
just cldii    # Agentic setup (with reporting)
just cldit    # Interactive setup (asks questions)

Das Justfile selbst bleibt einfach:

# Deterministic codebase setup
cldi:
  claude --init
 
# Agentic codebase setup
cldii:
  claude --init "/install"
 
# Interactive setup (asks questions)
cldit:
  claude --init "/install true"
 
# Deterministic maintenance
cldm:
  claude --maintenance
 
# Agentic maintenance (with reporting)
cldmm:
  claude --maintenance "/maintenance"

Teamkollegen und Agenten müssen Flags nie zweimal auswendig lernen. Sie führen just cldii aus und es funktioniert.

--init-only ist das Pipeline-Flag. Es führt den Hook aus, gibt einen Exit-Code zurück und beendet sich. Keine interaktive Sitzung dabei.

Beim Onboarding glänzt das. Ein neuer Entwickler tippt just cldit und der Agent führt ihn durch:

Agent: How should I handle the database?

┌─ Database Setup ─────────────────────────────────┐
│  ○ Fresh database (Recommended)                  │
│  ○ Keep existing                                 │
│  ○ Skip database setup                           │
└──────────────────────────────────────────────────┘

Der Agent fragt nach dem Installationsmodus, Umgebungsvariablen und ob zuerst die Voraussetzungen geprüft werden sollen. Er passt sich den Antworten an und führt nur die passenden Schritte aus.

Skripte können das nicht. Sie spielen immer dasselbe Band ab. Agenten können mittendrin anhalten, eine Rückfrage stellen und basierend auf der Antwort verzweigen.

Setup-Hooks sind eines von 12 Lifecycle-Events im Hook-System. Die Konfiguration liegt in .claude/settings.json:

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.py",
            "timeout": 120
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Das Hook-Skript führt deine Befehle aus und protokolliert alles:

def main():
    # Install backend dependencies
    run(["uv", "sync"], cwd="apps/backend")
 
    # Install frontend dependencies
    run(["npm", "install"], cwd="apps/frontend")
 
    # Initialize database
    run(["uv", "run", "python", "init_db.py"], cwd="apps/backend")
 
    # Tell Claude what happened
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "Setup",
            "additionalContext": "Setup complete. Run 'just be' and 'just fe' to start."
        }
    }))

Der /install Slash-Befehl greift das Log und schreibt die Ergebnisse auf:

---
description: Run setup and report installation results
---
 
## Workflow
 
1. Run /prime to understand the codebase
2. Read the log file at .claude/hooks/setup.init.log
3. Analyze for successes and failures
4. Write results to app_docs/install_results.md
5. Report to user

Wenn etwas kaputt geht, hat der Agent bereits den Kontext, um es zu diagnostizieren. Liste die üblichen Fehlermodi im Prompt auf, und der Agent geht das Fix-Playbook selbständig durch.

Denk an die Onboarding-Zeit im Verhältnis zu der Geschwindigkeit, mit der dein Team wachsen soll. Könnte ein Prompt Setup und Installation für einen neuen Mitarbeiter übernehmen? Könnte er jeden Schritt klar machen, indem er fragt, bevor er handelt?

Ja, auf beide Fragen. Agenten sind gut genug dafür. Das fehlende Stück ist Standardisierung.

Determinismus erhalten: Der Hook führt jedes Mal dasselbe Skript aus. Null LLM-Varianz während der Ausführung. Der Agent schaut sich die Ergebnisse nur nach der deterministischen Arbeit an.

CI-kompatibel: GitHub Actions führt claude --init-only aus und bekommt einen sauberen Exit-Code zurück.

Interaktiv, wenn es darauf ankommt: Neue Mitarbeiter werden durch das Setup geführt. Alle anderen nutzen die schnelle Version.

Ein lebendes Dokument, das sich ausführt: Dein Installationsprozess lebt jetzt in natürlicher Sprache, eingebettet in Prompts, die Agenten befolgen. Updates passieren durch Bearbeiten des Prompts.

Fang einfach an. Schreibe ein .claude/hooks/setup_init.py-Skript, das deine Dependencies installiert, verdrahte es in .claude/settings.json, dann füge einen /install-Befehl hinzu, der das Log liest und zurückmeldet. Wickle das Ganze in ein Justfile, damit dein Team just install ausführt und nicht mehr darüber nachdenkt.

Brauchst du etwas Leichteres? Wenn du nur verschiedenen Kontext je nach Sitzungstyp laden willst, reicht meist ein Slash-Befehl. Kein Installationsskript nötig.

Setup-Hooks zahlen sich am meisten aus, wenn du einen Befehl willst, der die Welt installiert, die Fehler diagnostiziert und neue Entwickler durch jeden Schritt führt. Skripte liefern die Gewissheit. Agenten liefern das Urteilsvermögen. Wenn dein Team zwischen Windows, Linux und macOS wechselt, lies die plattformübergreifenden Hook-Muster, damit dasselbe Setup auf jedem OS läuft.