Einen begrenzten Projektkontext-Hook zum Claude Code-Sitzungsstart hinzufügen

Ein Claude Code-Hook ist ein Befehl, den die Anwendung an einem benannten Sitzungspunkt ausführt. Diese Anleitung ergänzt einen projektbezogenen SessionStart -Hook, der den aktuellen Git-Branch liest und beim Starten oder Fortsetzen eines Gesprächs eine kurze Kontextzeile liefert. Grundlage ist Anthropics aktuelle Hook-Referenz, geprüft am 19. Oktober 2026. BIG CHANGE prüfte das Skript direkt mit Node und die Einstellungs-JSON; wir haben keinen von Claude Code aufgerufenen Hook und keine Modellantwort getestet.

Die große Veränderung

• Was sich ändert: Dieser Projekt-Hook SessionStart liefert beim Gesprächsstart oder bei der Fortsetzung in Claude Code eine kurze Git-Branch-Zeile.
• Warum das wichtig ist: Der aktuelle Branch gelangt beim Start oder Fortsetzen ohne erneutes manuelles Einfügen in den Sitzungskontext.
• Worauf zu achten ist: Kontext erzwingt keine Regel und garantiert keine Modellantwort. Prüfe die tatsächliche Übertragung beim Start und Fortsetzen in deinem vertrauenswürdigen Projekt.

Vor der Installation

Nutze ein Git-Projekt, das du ändern darfst. Claude Code, Node.js und Git müssen im selben Terminal verfügbar sein, und du brauchst die Erlaubnis, die Projektdatei .claude/settings.json zu bearbeiten. Prüfe node --version, git --version und claude --version. Auf dem Vorbereitungsrechner waren Claude Code 2.1.301 und Node 24.19.0 vorhanden; diese beobachteten Versionen sind keine Mindestanforderungen.

Prüfe den Branch-Namen vor der Übermittlung an ein Modell. Er kann Kunden-, Ticket- oder Vorfallsnamen enthalten. Zeichenfilterung und Kürzung entfernen diese Bedeutung nicht. Installiere dieses Beispiel nur, wenn der Name für den Modellkontext freigegeben ist. Andernfalls ändere das Skript auf einen freigegebenen, unvertraulichen Status und prüfe diese Änderung vor Installation. Anthropics Dokumentation zur Datennutzung erklärt die Datenverarbeitung des Dienstes; beachte außerdem deine Projektberechtigungen.

Hook-Befehle laufen mit deinen Benutzerrechten. Prüfe vor Aktivierung vorhandene Projekt- und Benutzer-Hooks, Organisationsregeln und das vollständige Skript. Projekteinstellungen können eingecheckt werden; .claude/settings.local.json bleibt lokal. Dieses Beispiel nutzt die Projekteinstellungsdatei, um die Konfiguration auf das Projekt zu begrenzen.

Die beiden Dateien installieren

1. Erstelle .claude/hooks/ im Projekt. Speichere den vollständigen Block als .claude/hooks/session-context.cjs:

'use strict';

const { execFileSync } = require('node:child_process');

const project = process.env.CLAUDE_PROJECT_DIR;
if (!project) {
  process.stderr.write('CLAUDE_PROJECT_DIR is unavailable\n');
  process.exit(1);
}

try {
  const raw = execFileSync('git', ['-C', project, 'branch', '--show-current'], {
    encoding: 'utf8',
    timeout: 1500,
    maxBuffer: 4096,
    stdio: ['ignore', 'pipe', 'pipe'],
  }).trim();
  const branch = raw ? raw.replace(/[^A-Za-z0-9._/-]/g, '_').slice(0, 80) : 'detached HEAD';
  process.stdout.write(`Current project branch: ${branch}\n`);
} catch {
  process.stderr.write('Could not read the project branch; check Git and project path\n');
  process.exit(1);
}

Der Git-Unterprozess hat ein Zeitlimit von 1,5 Sekunden und einen Ausgabepuffer von 4.096 Byte. Ein leeres Branch-Ergebnis, etwa bei abgelöstem HEAD, wird zu detached HEAD. Ein fehlender Projektpfad oder Git-Fehler erzeugt eine kurze stderr-Diagnose und Exitcode 1.

2. Öffne deine vorhandene Datei .claude/settings.json. Führe den folgenden Eintrag hooks.SessionStart mit den anderen Einstellungen und Hook-Gruppen zusammen und bewahre bestehende Einträge. Der Block zeigt die vollständige settings.example.json aus dem geprüften Paket. Enthält deine Datei bereits SessionStart -Einträge, ergänze diese Gruppe im Array, statt es zu ersetzen.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.cjs"],
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Das Muster erfasst neue und fortgesetzte Sitzungen. Anthropic dokumentiert auch clear, compact und fork als Quellen für SessionStart ; dieses Beispiel lässt sie bewusst aus. Das Feld args wählt die exec-Form: Claude Code ruft node mit dem aufgelösten Projektskriptpfad als einem Argument auf, ohne Shell-Quoting oder -Interpretation. Unter Windows muss node.exe als echte ausführbare Datei auflösbar sein; ein .cmd -Shim ist ungeeignet. Das Hook-Zeitlimit von fünf Sekunden ist vom Git-Limit von 1,5 Sekunden getrennt.

Erst das Skript, dann Claude Code prüfen

3. Führe vor dem Öffnen von Claude Code das Skript im Projektterminal aus und vergleiche die Ausgabe mit Git. In PowerShell:

$env:CLAUDE_PROJECT_DIR = (Get-Location).Path
node .claude/hooks/session-context.cjs
git branch --show-current

In Bash:

CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/session-context.cjs
git branch --show-current

Erwartet wird genau eine stdout-Zeile, Current project branch: BRANCH, wobei BRANCH das Git-Ergebnis nach Zeichenfilterung und der Grenze von 80 Zeichen ist. Bei abgelöstem HEAD erscheint Current project branch: detached HEAD. Der direkte Test belegt nur die lokale Ausführung in diesem Terminal. Bei unserer Vorbereitung stimmte das gewöhnliche Branch-Ergebnis mit Git überein; fehlende und ungültige Projektpfade ergaben leeres stdout, eine stderr-Diagnose und Exitcode 1. Die Begrenzung langer Namen und die Rückfalllösung für abgelöstes HEAD haben wir im Quelltext geprüft, aber nicht ausgeführt.

4. Starte einen frischen interaktiven Claude Code-Prozess im vertrauenswürdigen Projekt mit claude --debug-file STARTUP_PRIVATE_LOG und einem privaten Pfad unter deiner Kontrolle. Prüfe Projekt- und Benutzer-Hooks vor dem Bestätigen des Arbeitsbereichvertrauens. Suche im Debugprotokoll nach einem SessionStart -Ereignis mit Quelle startup, gewähltem Skriptpfad, Exitstatus und Ausgabebehandlung. Frage Claude nach dem empfangenen Branch-Kontext, ohne Werkzeuge oder erneutes Git-Lesen zu erlauben. Vergleiche Antwort und Protokoll mit dem direkten Ergebnis. Hook-stdout gelangt in Claudes Kontext; eine sichtbare Nachricht in der Oberfläche ist nicht zugesichert.
5. Beende die Sitzung. Setze sie in einem getrennten Prozess fort mit claude --debug-file RESUME_PRIVATE_LOG --resume, prüfe dann das Ereignis SessionStart resume und wiederhole die Frage ohne Werkzeug oder erneutes Git-Lesen. Halte beide Protokolle privat; sie können Projektdetails enthalten. Ein nicht interaktiver -p - oder SDK-Lauf zeigt nicht dieselbe Vertrauensabfrage und kann Repository-Hooks automatisch ausführen; nutze deshalb den interaktiven Ablauf. Anthropic sagt, sein Dateibeobachter übernimmt Einstellungsänderungen normalerweise, aber ein neuer Prozess macht den Start- und Fortsetzungstest klarer.

Ändert die normale Projektarbeit später den Branch, wiederhole direkten Test und neue Sitzung, um die Zeile zu prüfen. Wechsle den Branch nicht nur, um eine angebliche Prüfung dieser Anleitung zu behaupten.

Wenn der Hook nicht läuft

Beginne mit dem direkten Skriptergebnis und prüfe dann JSON-Zusammenführung, Schreibweise von SessionStart , Muster startup|resume , Projektwurzelpfad, Verfügbarkeit von node und git, Arbeitsbereichvertrauen und Debugfehler. Fehlt CLAUDE_PROJECT_DIR , erscheint CLAUDE_PROJECT_DIR is unavailable auf stderr. Ein falscher Projektpfad oder Git-Fehler meldet Could not read the project branch; check Git and project path. Beide enden mit 1 und ohne Kontextzeile. Ein SessionStart -Fehler ist diagnostisch und nicht blockierend; er ist keine Aktionssperre. Anthropic dokumentiert PreToolUse zur Steuerung einer Werkzeugaktion; das ist ein anderes Ereignis und benötigt einen eigenen geprüften Entwurf.

Das Skript führt nur lokales Git aus, ohne Netzwerk- oder Modellaufruf. Claude Code-Start, Fortsetzung und Antworttests können dein Konto-, Anbieter- oder Modellkontingent verbrauchen; Anthropics Kostenleitfaden nennt aktuelle Bedingungen. Diese Anleitung legt keinen Preis fest und berichtet keinen bezahlten Sitzungstest.

Für eine getrennte Aufgabe im bereits laufenden Gespräch erklärt unsere Anleitung zur Kontextprüfung und Fortsetzung einer Claude Code-Sitzung die Kontextinspektion und Weiterarbeit. Sie konfiguriert diesen Start-Hook nicht.

Quellen und weiterführende Lektüre

• Anthropic, Claude Code-Hook-Referenz — Aktuelle Primärspezifikation, geprüft am 19. Oktober 2026. Dokumentiert Quellen und Muster von SessionStart , exec-Form args, Pfadplatzhalter, stdout-Kontext, Nachladen von Einstellungen, Vertrauen, Debugprotokolle und nicht blockierende Fehler. Dokumentation, keine Hook-Ausführung durch BIG CHANGE.
• Anthropic, Aktionen mit Hooks automatisieren — Offizielle Einführung in Einrichtung und Tests. Das konkrete Skript und die Einstellungen sind ein begrenztes, für diese Anleitung geprüftes BIG CHANGE-Beispiel, kein kopiertes Testergebnis des Anbieters.
• Anthropic, Claude Code einrichten — Installation und Umgebungsanforderungen. Prüfe die aktuellen Plattformanweisungen vor Nutzung des Beispiels.
• Anthropic, Claude Code-Datennutzung — Aktuelle Datenbedingungen des Anbieters vor Übermittlung von Branch-Informationen an den Modellkontext; die Projektfreigabe ist eine gesonderte Entscheidung.
• Anthropic, Kosten wirksam verwalten — Aktuelle Konto- und Nutzungshinweise für interaktive Prüfungen. Das lokale Git-Skript ruft selbst weder Modell noch Netzwerk auf.