claude-handoff

Verwandle jede Claude Code-Sitzung – selbst eine abgestürzte – in ein sauberes handoff.md, von dem eine andere KI weiterarbeiten kann. Und gib Claude Code ein dauerhaftes Projektgedächtnis, destilliert aus deiner eigenen Geschichte.

chf

Das war's. Deine letzte Sitzung wird zu handoff.md: das Gespräch ohne das Rauschen, die geänderten Dateien, die ausgeführten Befehle – beginnend mit Anweisungen für den empfangenden Assistenten, sodass du es direkt in Gemini, GPT, claude.ai oder eine neue Claude Code-Sitzung einfügen kannst, ohne zusätzliche Aufforderung.

Claude Code speichert jede Sitzung lokal als JSONL (~/.claude/projects/…/*.jsonl), voller Tool-Aufrufe, Tool-Ergebnisse, Denkblöcke und Systemerinnerungen. Bestehende Exporteure kippen das alles in Markdown. claude-handoff erzeugt stattdessen ein Handoff-Dokument – und, da es deine gesamte Geschichte lesen kann, auch eine Projektgedächtnis-Übersicht.

• Null Abhängigkeiten. Nur Standardbibliothek, Python 3.9+. Ein Neun-Modul-Paket – auch als generiertes Einzeldatei-Skript, das du per curl holen und prüfen kannst.

• Deterministisch standardmäßig. Kein API-Aufruf, keine Kosten, funktioniert offline.

• --llm für eine echte Zusammenfassung. Claude, OpenAI oder Gemini über deinen eigenen API-Schlüssel – oder --llm claude-cli, das deine lokal installierte Claude Code CLI auf deinem bestehenden Pro/Max-Plan nutzt: ganz ohne API-Schlüssel.

• Rauschfrei. Entfernt Tool-Ergebnisse, Denkblöcke, Systemerinnerungen, Subagent-Geschwätz, Slash-Command-Hüllen. Behält Benutzerabsicht, Assistentenantworten, geänderte Dateien, ausgeführte Befehle – einschließlich der Dateien und Befehle von Subagenten (agent-*.jsonl), deren vollständige Transkripte hinter --include-sidechains bleiben.

• Projektgedächtnis. chf --brief destilliert die GESAMTE Sitzungshistorie eines Projekts in eine lebendige Übersicht (Entscheidungen, Fixes, Konventionen, offene Threads – mit Sitzungszitaten); --install-brief-hook injiziert sie in jede neue Claude Code-Sitzung, sodass Claude das Projekt bereits kennt.

• Sicher zum Einfügen. Geheimnisartige Zeichenfolgen (API-Schlüssel, Tokens, password=…) werden aus jeder Ausgabe entfernt – das Handoff, das du in einen Web-Chat einfügst, ist ebenfalls ein Egress. --anonymize geht für öffentliche Weitergabe noch weiter.

Voraussetzungen

Keine Drittanbieter-Python-Pakete, niemals – alles läuft auf der Standardbibliothek.

Related MCP server: Longhand

Installation

pipx install claude-handoff        # or: pip install claude-handoff

brew install Vasilispapg/tap/claude-handoff   # Homebrew

# or just grab the generated single-file build — stdlib-only, auditable:
curl -O https://raw.githubusercontent.com/Vasilispapg/claude-handoff/main/single/claude_handoff.py
python3 claude_handoff.py --list

Die Installation des Pakets gibt dir zwei identische Befehle: claude-handoff und den kurzen Alias chf. Tab-Vervollständigung:

eval "$(claude-handoff --completions zsh)"    # bash works too

60 Sekunden: Wähle deine Situation

Eine Sitzung ist abgestürzt, das Nutzungslimit erreicht, oder du hast das Terminal geschlossen:

chf -o clipboard

…dann füge es in claude.ai, ChatGPT, Gemini – oder eine neue claude-Sitzung ein. Funktioniert mit jeder alten Sitzung; es musste nichts vor dem Absturz installiert sein.

Arbeit von Claude Code auf ein anderes Modell übertragen:

chf --fit 32k -o clipboard         # sized to the receiver's context window

„Welche Sitzung war das, in der wir über CORS gesprochen haben?"

chf --list --grep "CORS"           # every match, with a 🔍 context preview
chf --grep "CORS"                  # or export the newest match directly

Claude Code ein dauerhaftes Gedächtnis für dieses Projekt geben:

chf --brief --llm claude-cli       # distill ALL sessions → one cited brief
chf --install-brief-hook           # every new session starts knowing it

Eine echte Zusammenfassung statt des Transkripts (Ziel / Entscheidungen / Stand / Nächstes):

chf --llm claude-cli               # your Claude Code login — no API key

Ein claude.ai- oder ChatGPT-Web-Chat statt einer Terminal-Sitzung:

chf conversations.json --list      # each app's data export works as input
chf conversations.json --name "webhook bug"

Projektgedächtnis (--brief)

Claude Code vergisst alles zwischen Sitzungen – aber die gesamte Geschichte liegt auf deiner Festplatte. chf --brief liest jede Sitzung des aktuellen Projekts und schreibt ein Gedächtnisdokument nach ~/.claude/briefs/<project>.md:

• eine sachliche Sitzungs-Zeitleiste + am häufigsten berührte Dateien (deterministisch, kostenlos);

• mit --llm ein destilliertes Gedächtnis – Entscheidungen mit ihrem Warum, behobene Fehler, Konventionen, offene Threads – jeder Punkt zitiert mit der Sitzungs-ID, aus der er stammt (chf --name <id> öffnet die Quelle).

Notizen pro Sitzung werden zwischengespeichert, sodass das Aktualisieren nach neuen Sitzungen nur für die neuen bezahlt – und eine Monster-Sitzung (über ~120k Zeichen) wird innerhalb der Notiz map-reduziert, sodass der Gedächtnispfad nie abgeschnitten wird: Nichts wird stillschweigend verworfen, egal bei welcher Größe.

chf --install-brief-hook

installiert zwei Hooks: SessionStart injiziert die Übersicht als Kontext (Claude startet bereits mit Projektkenntnis – auch nach /compact erneut injiziert), SessionEnd aktualisiert automatisch den sachlichen Teil kostenlos. Von einem Hook läuft niemals ein LLM; der destillierte Teil wird nur aktualisiert, wenn du es sagst. Die Übersicht trägt einen Frische-Stempel, und sowohl die Datei als auch die Injektion warnen, wenn neuere Sitzungen existieren. Vollständig lokal; Redaktion gilt wie überall.

→ Schritt-für-Schritt-Mechanik, die ehrliche Kostentabelle und ein kompletter Tagesablauf: docs/GUIDE.md.

Automatisierung

chf --install-hook                 # SessionEnd + PreCompact → handoff to ~/.claude/handoffs/
chf --install-brief-hook           # SessionStart/End + PreCompact → project memory (above)

PreCompact ist wichtig: Direkt bevor Claude Code den Kontext einer langen Sitzung kompaktiert, erfassen beide Hooks den Zustand – das Handoff bewahrt Details, die die Kompaktierung gleich ausquetschen würde, und das Übersichts-Skelett bleibt mitten in der Sitzung frisch.

Beide bearbeiten ~/.claude/settings.json nicht-destruktiv, sind idempotent und haben passende --uninstall-*-Flags. Hook-Fehler brechen die Host-Sitzung nie, und Hooks lösen niemals LLM-Aufrufe aus oder erstellen eigenständig Dateien.

Wie die Ausgabe aussieht

# Conversation handoff

> To the receiving assistant: … you are taking over …

## Session
- Project: /home/you/myapp (branch main)
- When: 2026-08-20 09:00 → 09:04
- Activity: 2 user messages, 4 assistant replies, 4 tool calls

## Files created / modified
- /home/you/myapp/auth.py

## Commands run
- python -m pytest tests/test_auth.py -q

_🤖 2 subagent(s) contributed to the work above (--include-sidechains for their transcripts)._

## Conversation
### 🧑 User
the login breaks on unicode passwords…
### 🤖 Assistant
Found it — ascii encoding. Changed to utf-8, tests pass.

Häufige Befehle

chf                                # latest session → handoff.md
chf -i                             # numbered picker; "1,3" or "2-4" merges several
chf --list                         # what sessions do I have? (title · first prompt)
chf --list --format json           # the same, machine-readable
chf --name "login bug"             # newest session whose title/prompt matches
chf "login bug"                    # same — a non-path argument is a name search
chf --grep "CORS"                  # newest session that *talked about* CORS
chf --grep CORS --grep auth        # …that talked about BOTH (AND)
chf a.jsonl b.jsonl                # several paths → ONE merged handoff
chf --project myrepo               # latest session of a specific project
chf path/to/session.jsonl -o -     # explicit file → stdout
chf -o clipboard                   # straight to the clipboard — go paste it
chf --last 5                       # only the last 5 user turns
chf --since 2h                     # only the last 2 hours of the session
chf --fit 32k                      # sized to fit a 32k-token context
chf --include-tools                # keep collapsed per-tool-call detail
chf --include-sidechains           # append full subagent transcripts
chf --anonymize                    # public-safe: ~ paths, no emails/IPs/username
chf --project myrepo --merge       # whole project in ONE handoff, oldest → newest
chf --format json -o session.json  # machine-readable handoff

# LLM summaries (goal / decisions / current state / next steps):
chf --llm claude-cli               # your Claude Code login — no API key
chf --llm ollama                   # local model — fully offline
chf --llm claude                   # Anthropic API   (ANTHROPIC_API_KEY)
chf --llm openai --model gpt-4o    # OpenAI API      (OPENAI_API_KEY)
chf --llm gemini --with-transcript # Google API      (GEMINI_API_KEY)
chf --llm claude-cli --focus "emphasize the API decisions"

# project memory:
chf --brief                        # free factual brief (timeline + files)
chf --brief --llm claude-cli       # + distilled decisions/fixes/conventions

Wo sucht es? Sitzungen liegen im globalen Store von Claude Code (~/.claude/projects), du kannst chf also von überall ausführen. Wenn dein aktuelles Verzeichnis ein Projekt ist (oder ein Unterordner davon), beschränkt es sich auf die Sitzungen dieses Projekts; ein übergeordneter „Master-Ordner" beschränkt sich auf alle Projekte darunter; --any ignoriert das Verzeichnis vollständig. Die automatische Auswahl überspringt fast leere Sitzungen (wie den Stub, den claude /login hinterlässt), sodass „neueste" deine neueste echte Unterhaltung bedeutet – ein expliziter Pfad, --name oder -i gewinnt immer.

Große Sitzungen. Transkripte über einen Durchgang (~400k Zeichen) werden im Map-Reduce-Stil zusammengefasst: Notizen pro Chunk, dann eine Synthese – nichts wird stillschweigend verworfen, und fertige Chunks werden in ~/.cache/claude-handoff zwischengespeichert, sodass ein unterbrochener Lauf kostenlos fortgesetzt wird. Chunks laufen bei API-Anbietern 4-fach parallel; claude-cli und ollama bleiben bewusst sequenziell. Im Terminal erhältst du einen Live-Fortschrittsbalken:

[█████████░░░░░░░░░░░░░░░] 3/9 chunks | 4m12s elapsed | ~8m left | summarizing part 4/8 (199,867 chars)…

Sitzungen mit API-usage-Daten erhalten außerdem eine Tokens-Zeile im Kopfbereich, und jeder Lauf meldet die ≈Token-Größe der Ausgabe.

Datenschutz & Zero-Trust

• Nichts wird irgendwohin gesendet, außer du übergibst --llm – der deterministische Modus ist vollständig offline.

• Redaktion ist für jede Ausgabe aktiv, nicht nur für LLM-Verkehr: geheimnisartige Zeichenfolgen (API-Schlüssel, Tokens, JWTs, password=…) werden aus dem Handoff selbst, aus Hook-Dateien und MCP-Antworten entfernt – ein eingefügtes Dokument ist ebenfalls Egress. --no-redact deaktiviert sie pro Lauf (und ist in der Konfigurationsdatei bewusst nicht erlaubt).

• --anonymize reduziert zusätzlich dein Home-Verzeichnis auf ~ und ersetzt E-Mails, IPv4-Adressen und deinen Benutzernamen durch Platzhalter – zum Einfügen in öffentliche Issues und Foren.

• --llm claude-cli und --llm ollama halten alles innerhalb von Konten und Maschinen, die du bereits kontrollierst.

• Prompt-Injection-Schutz: Transkripte enthalten regelmäßig unvertrauten Text (Webseiten in Tool-Ergebnissen, eingefügte READMEs). Jeder Prompt, der ein Transkript konsumiert, die Handoff-Präambel und der Brief-Injektions-Wrapper rahmen diesen Inhalt als Daten, nicht als Anweisungen – durch Tests abgesichert. Eine Abschwächung, kein Beweis; der Parser selbst führt nie etwas aus.

Konfiguration (optional)

Lege Standardwerte, die du immer verwendest, in ~/.config/claude-handoff/config.json ab (CLI-Flags gewinnen immer; CLAUDE_HANDOFF_CONFIG überschreibt den Pfad):

{ "llm": "claude-cli", "fit": "32k", "include_tools": true }

Erlaubte Schlüssel: llm, model, fit, output, include_tools, include_sidechains, max_chars, anonymize, focus. Sicherheitsschalter (no_redact) sind bewusst nicht konfigurierbar – die Redaktion zu schwächen muss eine explizite Wahl pro Lauf sein. Eine defekte Konfiguration warnt und wird ignoriert, nie fatal.

Umgebungsvariablen

claude-cli benötigt keine Variable – es ruft deine installierte Claude Code-CLI auf, die über deinen Pro/Max-Plan abgerechnet wird (führe claude einmal aus, um dich anzumelden).

MCP-Server

Jeder MCP-Client (Claude Desktop, Claude Code, …) kann Handoffs direkt abrufen:

claude mcp add claude-handoff -- claude-handoff --mcp

Tools: list_sessions (was auf dieser Maschine ist) und handoff (erstellt das Dokument für eine Sitzung nach Name/Projekt/Pfad; übergib anonymize für eine teilbare Version). Deterministisch standardmäßig – ein MCP-Client kann LLM-Zusammenfassungen nur auslösen, wenn du den Server mit --allow-llm startest.

Fehlerbehebung

claude-handoff: command not found nach pip install pip legt Skripte in ein Benutzer-Bin-Verzeichnis, das möglicherweise nicht im PATH liegt. Verwende pipx install claude-handoff oder brew – beide verwalten den PATH – oder füge ~/.local/bin (Linux) / ~/Library/Python/3.x/bin (macOS) zu deinem PATH hinzu.

„Keine Sitzungen unter ~/.claude/projects gefunden" Du bist auf einer Maschine (oder einem Benutzer), auf der Claude Code nicht ausgeführt wurde, oder dein Store liegt woanders – weise CLAUDE_HOME darauf. Innerhalb eines Projektordners beschränkt sich das Tool auf dieses Projekt; übergib --any, um alles zu durchsuchen.

Es hat die falsche Sitzung ausgewählt „Neueste" überspringt fast leere Stubs, ist aber immer noch nur die neueste Datei. Verwende -i (Auswahl), --name "Teil des Titels" oder --grep "etwas Gesagtes".

--llm claude-cli schlägt fehl oder fragt nach Authentifizierung
Führe claude einmal aus und melde dich an (/login). Es funktioniert auch, wenn es aus innerhalb einer Claude-Code-Sitzung aufgerufen wird – geerbte CLAUDE*-Umgebungsvariablen werden entfernt, sodass sich die verschachtelte CLI wie eine frische authentifiziert.

"Setze ANTHROPIC_API_KEY … um --llm claude zu verwenden"
API-Anbieter benötigen einen Schlüssel in der Umgebung – siehe Tabelle oben. Gar kein Schlüssel? Verwende --llm claude-cli (Abonnement) oder --llm ollama (lokal).

--fit lässt sich nicht mit --llm / --max-chars kombinieren
--fit dimensioniert die deterministische Ausgabe selbst. Wenn du es nicht eingegeben hast, setzt deine Konfigurationsdatei wahrscheinlich fit – überschreibe es, indem du ein explizites --max-chars entfernst, oder entferne den Schlüssel.

Die Kurzfassungs-Injektion warnt: „Es existieren neuere Sitzungen als diese Kurzfassung“
Das ist der Frischestempel, der seine Arbeit tut: Führe chf --brief --llm claude-cli aus, um neu zu destillieren (zwischengespeichert – nur neue Sitzungen werden bezahlt). Der faktenbasierte Teil aktualisiert sich selbst, wenn der SessionEnd-Hook installiert ist.

Etwas hat stillschweigend nichts getan?
Fehlertolerante Pfade (korrupte JSONL-Zeilen, nicht lesbare Dateien, Cache-Probleme) lassen den Lauf nie abstürzen – füge --debug (oder CLAUDE_HANDOFF_DEBUG=1) hinzu, um genau zu sehen, was übersprungen wurde und warum. Hooks melden ihre Fehler immer auf stderr, während sie weiterhin mit 0 beenden.

Verstümmelte Zeichen unter Windows
Setze PYTHONUTF8=1 (die CI führt die gesamte Suite so aus).

Vollständige Flag-Referenz

Roadmap

• Gemini-Exporte als Eingabe (Google Takeout liefert nur HTML – bring einen echten, redigierten Export zum Entwickeln mit)

• Sitzungsketten: automatisch /compact-fortgesetzte Sitzungen erkennen und anbieten, die Abstammung zusammenzuführen (--follow)

PRs willkommen.

Wie es sich vergleicht

Dieser Bereich ist nicht leer – er ist fragmentiert. Wähle das Tool, das zu deiner Situation passt:

• Exporteure – claude-conversation-extractor, claude-code-log, claude-code-transcripts, claude-to-markdown – wandeln Transkripte in lesbares Markdown/HTML um, einschließlich Tool-Rauschen, ohne Handoff-Rahmen.

• CLI-übergreifende Sitzungsverschieber – cli-continues (npm i -g continues) liest die nativen Sitzungsspeicher von 16 Coding-CLIs (einschließlich Claude Code) und injiziert ein Kontextdokument in ein anderes Terminal-Tool. Ausgezeichnet für Claude Code → Codex/Cursor/Gemini CLI; kann aber keine Web-Chats ansprechen, macht keine LLM-Zusammenfassung und benötigt Node 22.5+.

• In-Sitzungs-Handoff-Fähigkeiten/Plugins – thepushkarp/handoff, claude-session-handoff, claude-code-handoff – großartig, wenn du daran denkst, sie vor dem Ende der Sitzung auszuführen; das Modell schreibt die Zusammenfassung mit dem Kontext deiner Sitzung, und die Ausgabe zielt auf die nächste Claude-Sitzung.

• Browser-Erweiterungen – Handoff, LLM Context Bridge, ContextSwitch – übertragen Web-Chats zwischen ChatGPT/Claude/Gemini; sie können keine Claude-Code-Sitzungen sehen.

claude-handoff ist die Post-hoc-, überall-einfügbare Ecke dieser Karte: Es arbeitet mit dem JSONL nach dem Ereignis – alte Sitzungen, abgestürzte Sitzungen, Sitzungen, die das Nutzungslimit erreicht haben – benötigt nichts vorinstalliertes, kostet standardmäßig null Token, kann eine echte Zusammenfassung schreiben, wenn du eine anforderst (--llm), und erzeugt ein Dokument, das jedes empfangende Modell aufnehmen kann, einschließlich claude.ai, ChatGPT und Gemini im Browser oder auf deinem Telefon. Und mit --brief ist es das einzige, das diese Geschichte in dauerhaftes Projektgedächtnis verwandelt.

Entwicklung

git clone https://github.com/Vasilispapg/claude-handoff && cd claude-handoff
python3 -m unittest discover -s tests -v      # the whole suite (no deps needed)
python3 -m claude_handoff tests/fixtures/agent_session.jsonl -o -   # smoke run
python3 scripts/build_single.py --check       # single-file build is fresh
uvx ruff check claude_handoff scripts tests   # lint (config in pyproject)

Der Laufzeitcode befindet sich im Paket claude_handoff/; single/claude_handoff.py ist generiert – baue es mit python3 scripts/build_single.py nach jeder Paketänderung neu (CI schlägt fehl, wenn es veraltet ist). Neues Parser-Verhalten beginnt mit einer redigierten Fixture in tests/fixtures/ – siehe CONTRIBUTING.md und AGENTS.md (Anweisungen und Invarianten für menschliche und KI-Beitragende).

Mehr erfahren

docs/GUIDE.md – ein Tag mit claude-handoff: Durchlauf, wie --brief Schritt für Schritt funktioniert, ehrliche Kostentabelle, Spickzettel · INDEX.md – Dateizuordnung · docs/DEVELOPMENT.md – Architektur, JSONL-Schema-Notizen, Designentscheidungen · AGENTS.md – Beitragsleitfaden für KI-Codierungsagenten · CONTRIBUTING.md · CHANGELOG.md

Lizenz

MIT

mcp-name: io.github.Vasilispapg/claude-handoff