claude-handoff

Summarize & export a Claude Code session into one clean handoff.md you can paste into Gemini, GPT, or another Claude — without the noise.

Claude Code stores every session locally as JSONL (~/.claude/projects/…/*.jsonl), full of tool calls, tool results, thinking blocks and system reminders. Existing exporters dump all of that into markdown. claude-handoff instead produces a handoff document: the actual conversation, what files were touched, what commands ran, and (optionally) an LLM-written summary of goal / decisions / current state / next steps — so the next model can just continue the work.

• Zero dependencies. One Python file, stdlib only. Python 3.9+.
• Deterministic by default. No API call, no cost, works offline.
• --llm when you want a real summary. Claude, OpenAI or Gemini via your own API key — or --llm claude-cli, which runs your locally-installed Claude Code CLI on your existing Pro/Max plan: no API key at all.
• Noise-free. Drops tool results, thinking blocks, system reminders, subagent chatter, slash-command envelopes. Keeps user intent, assistant answers, files modified, commands run.

Install

pipx install claude-handoff        # or: pip install claude-handoff
# or just grab the file — it's a single stdlib-only script:
curl -O https://raw.githubusercontent.com/Vasilispapg/claude-handoff/main/claude_handoff.py
python3 claude_handoff.py --list

Usage

claude-handoff                     # latest session → handoff.md
claude-handoff --list              # what sessions do I have? (title · first prompt)
claude-handoff --name "login bug"  # newest session whose title/prompt matches
claude-handoff "login bug"         # same — a non-path argument is a name search
claude-handoff --project myrepo    # latest session of a specific project
claude-handoff path/to/session.jsonl -o -     # explicit file → stdout
claude-handoff --include-tools     # keep collapsed per-tool-call detail

# real LLM summary (goal / decisions / current state / next steps):
claude-handoff --llm claude-cli                 # uses your Claude Code login — no API key
export ANTHROPIC_API_KEY=sk-...
claude-handoff --llm claude
claude-handoff --llm openai --model gpt-4o
claude-handoff --llm gemini --with-transcript   # summary + cleaned transcript

Then paste handoff.md into any other model. The document opens with instructions to the receiving assistant, so no extra prompting is needed.

Auto-selection skips nearly-empty sessions (like the stub claude /login leaves behind) so "latest" means your latest real conversation. An explicit path or --name always wins.

What the output looks like

# 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

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

Flags

API keys (first set variable wins per provider):

Nothing is sent anywhere unless you pass --llm.

Roadmap

• claude.ai web chat exports (conversations.json from the official data export) as input
• ChatGPT / Gemini exports as input (handoff in both directions)
• --format json for programmatic use

PRs welcome.

How it compares

This space isn't empty — it's fragmented. Pick the tool that matches your situation:

• Exporters — claude-conversation-extractor, claude-code-log, claude-code-transcripts, claude-to-markdown — turn transcripts into readable Markdown/HTML, tool noise included, no handoff framing.
• Cross-CLI session movers — cli-continues (npm i -g continues) reads 16 coding CLIs' native session stores (Claude Code included) and injects a context doc into another terminal tool. Excellent for Claude Code → Codex/Cursor/Gemini CLI; but it can't target web chats, does no LLM summarization, and needs Node 22.5+.
• In-session handoff skills/plugins — thepushkarp/handoff, claude-session-handoff, claude-code-handoff — great if you remember to run them before the session ends; the model writes the summary using your session's context, and the output targets the next Claude session.
• Browser extensions — Handoff, LLM Context Bridge, ContextSwitch — transfer web chats between ChatGPT/Claude/Gemini; they can't see Claude Code sessions.

claude-handoff is the post-hoc, paste-anywhere corner of this map: it works on the JSONL after the fact — old sessions, crashed sessions, sessions that hit the usage limit — needs nothing installed in advance, costs zero tokens by default, can write a real summary when you ask for one (--llm), and produces a document any receiving model can pick up, including claude.ai, ChatGPT and Gemini in the browser or on your phone.

Docs

INDEX.md — file map · docs/DEVELOPMENT.md — architecture, JSONL schema notes, design decisions · AGENTS.md — instructions for AI coding agents · CONTRIBUTING.md · CHANGELOG.md

License

MIT