Markdown-Ausgabe

AI-translated from English; not yet reviewed by a fluent editor.

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

> Installiere einen kleinen SessionStart-Hook für den aktuellen Git-Branch im Claude Code-Kontext. Prüfe direkte Ausgabe, Start, Fortsetzung und Fehlerverhalten.

By BIG CHANGE Editorial

Published: 2026-10-20T00:22:54.831Z
Updated: 2026-10-20T00:22:54.831Z
Canonical: https://bigchange.ai/blog/claude-code-session-start-branch-context-hook-guide

![Conceptual charcoal illustration of an unbranded desktop monitor with one short orange stroke above two soft charcoal strokes; a keyboard rests in front.](https://bigchange.ai/api/media/file/claude-code-session-start-context-hero-v2.png)
AI-generated conceptual illustration by BIG CHANGE; no actual Claude Code interface, hook execution or model result is depicted.

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](https://code.claude.com/docs/en/hooks), 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](https://code.claude.com/docs/en/data-usage) 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`:

```javascript
'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.

```json
{
  "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:

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

In Bash:

```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](https://code.claude.com/docs/en/costs) 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](https://bigchange.ai/blog/claude-code-session-context-continue-guide) die Kontextinspektion und Weiterarbeit. Sie konfiguriert diesen Start-Hook nicht.

## Quellen und weiterführende Lektüre

- [Anthropic, Claude Code-Hook-Referenz](https://code.claude.com/docs/en/hooks) — 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](https://code.claude.com/docs/en/hooks-guide) — 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](https://code.claude.com/docs/en/setup) — Installation und Umgebungsanforderungen. Prüfe die aktuellen Plattformanweisungen vor Nutzung des Beispiels.
- [Anthropic, Claude Code-Datennutzung](https://code.claude.com/docs/en/data-usage) — Aktuelle Datenbedingungen des Anbieters vor Übermittlung von Branch-Informationen an den Modellkontext; die Projektfreigabe ist eine gesonderte Entscheidung.
- [Anthropic, Kosten wirksam verwalten](https://code.claude.com/docs/en/costs) — Aktuelle Konto- und Nutzungshinweise für interaktive Prüfungen. Das lokale Git-Skript ruft selbst weder Modell noch Netzwerk auf.

## Sources

- [Claude Code-Hook-Referenz](https://code.claude.com/docs/en/hooks) — Aktuelles primäres Anthropic-Handbuch, gegen den freigegebenen Stand vom 19. Oktober 2026 und nochmals beim Schreiben geprüft. Belegt SessionStart-Quellen startup/resume und Muster, command und args in exec-Form, Projektwurzelplatzhalter, stdout-Kontext, Einstellungsbeobachter, Arbeitsbereichvertrauen, Debugdateien, echte ausführbare Datei unter Windows und nicht blockierende SessionStart-Fehler. Produktbeschreibung; BIG CHANGE führte keinen von Claude aufgerufenen Hook aus. Kein festes Revisionsdatum war genannt.
- [Aktionen mit Hooks automatisieren](https://code.claude.com/docs/en/hooks-guide) — Offizielle Anthropic-Anleitung für Einrichtung und Tests. Stützt Konfiguration und Diagnose der Leser, keine Behauptung, BIG CHANGE habe das Beispiel in Claude Code ausgeführt. Das konkrete begrenzte Node-Skript und seine Einstellungen stammen aus dem getrennt geprüften lokalen Implementierungspaket.
- [Erweiterte Claude Code-Einrichtung](https://code.claude.com/docs/en/setup) — Offizielle Installations- und Umgebungsreferenz zur Prüfung lokaler Einrichtung. Bei der Vorbereitung wurde nur 2.1.301 beobachtet; daraus folgt keine Mindestversion.
- [Claude Code-Datennutzung](https://code.claude.com/docs/en/data-usage) — Offizielle kontobedingte Datenregeln. Der Artikel verlangt ihre Prüfung vor Branch-Übermittlung an das Modell; Filtern und Kürzen verhindern keine Offenlegung vertraulicher Kunden- oder Vorfallsnamen. Keine allgemeine Datenschutzgarantie wird abgeleitet.
- [Kosten wirksam verwalten](https://code.claude.com/docs/en/costs) — Offizielle Konto- und Modellnutzungshinweise für interaktive Start- und Fortsetzungstests. Das lokale Skript sendet keine Modell- oder Netzwerkanfrage, reale Claude-Sitzungen können jedoch Plan-, Anbieter- oder API-Kontingente verbrauchen. Kein Festpreis oder bezahlter Test wird behauptet.
- [Kontext prüfen und eine Claude Code-Sitzung fortsetzen](https://bigchange.ai/blog/claude-code-session-context-continue-guide) — Früherer BIG CHANGE-Artikel 414, nur für einen Kontextlink und die Beziehungsklassifikation. Er betrifft ein bestehendes Gespräch und dessen Fortsetzung, ist kein Beleg für die Hook-Implementierung und kein direkter datierter Vorgänger.