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. Stdlib only, Python 3.9+. A nine-module package — also shipped as a generated single-file script you can curl and audit.
• 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 — including the files and commands of subagents (agent-*.jsonl), whose full transcripts stay behind --include-sidechains.
• Project memory. chf --brief distills a project's ENTIRE session history into one living brief (decisions, fixes, conventions, open threads — with session citations); --install-brief-hook injects it into every new Claude Code session, so Claude starts already knowing the project.
• Safe to paste. Secret-looking strings (API keys, tokens, password=…) are redacted from every output — the handoff you paste into a web chat is egress too. --no-redact opts out.

Install

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

# tab completion (bash or zsh):
eval "$(claude-handoff --completions zsh)"

Installing the package gives you two commands: claude-handoff and its short alias chf — identical, use whichever you like typing.

Usage

claude-handoff                     # latest session → handoff.md
claude-handoff -i                  # pick from a numbered list
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 --grep "CORS"       # newest session that *talked about* CORS
claude-handoff --fit 32k           # handoff sized to fit a 32k-token context
claude-handoff --project myrepo    # latest session of a specific project
claude-handoff path/to/session.jsonl -o -     # explicit file → stdout
claude-handoff -o clipboard        # straight to the clipboard — go paste it
claude-handoff --last 5            # only the last 5 user turns
claude-handoff --since 2h          # only the last 2 hours of the session
claude-handoff --include-tools     # keep collapsed per-tool-call detail
claude-handoff --include-sidechains  # append full subagent transcripts
chf --last 5                       # `chf` = short alias, same tool

# claude.ai AND ChatGPT web chats too (each app's data export):
claude-handoff conversations.json --list
claude-handoff conversations.json --name "webhook bug"

# whole project in one handoff, oldest → newest:
claude-handoff --project myrepo --merge

# machine-readable:
claude-handoff --format json -o session.json
claude-handoff --list --format json   # session list as JSON

# shareable in public (issues, forums): ~ paths, no emails/IPs/username
claude-handoff --anonymize

# auto-handoff: write one for every session when it ends
claude-handoff --install-hook

# project memory: distill ALL sessions into one brief, inject at start
chf --brief --llm claude-cli       # build/refresh ~/.claude/briefs/<project>.md
chf --install-brief-hook           # every new session starts with it

# real LLM summary (goal / decisions / current state / next steps):
claude-handoff --llm claude-cli                 # uses your Claude Code login — no API key
claude-handoff --llm ollama                     # local model — fully offline
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.

Project memory (--brief)

Claude Code forgets everything between sessions — but the whole history is on your disk. chf --brief reads every session of the current project and writes one memory document: a factual session timeline + most-touched files (deterministic, free), and with --llm a distilled memory — decisions with their why, fixed bugs, conventions, open threads — every bullet cited with the session id it came from. Per-session notes are cached, so refreshing after new sessions only pays for the new ones. chf --install-brief-hook installs two hooks: SessionStart injects the brief as context (Claude starts already knowing your project), SessionEnd auto-refreshes the factual part — free, no LLM ever runs from a hook. The distilled part refreshes only when you say so; the brief carries a freshness stamp, and both the file and the injection warn when newer sessions exist. Fully local; redaction applies as everywhere.

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

_🤖 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.

Flags

API keys (first set variable wins per provider):

Nothing is sent anywhere unless you pass --llm.

Where does it look? Sessions live in Claude Code's global store (~/.claude/projects), so you can run claude-handoff from anywhere. If your current directory is a project (or a subfolder of one), it scopes to that project's sessions; a parent "master folder" scopes to every project under it; --any ignores the directory entirely.

Big sessions & privacy. Transcripts beyond one pass (~400k chars) are summarized map-reduce style: notes per chunk, then one synthesis — nothing is silently dropped, and finished chunks are cached in ~/.cache/claude-handoff so an interrupted run resumes for free. Secret-looking strings (API keys, tokens, password=…) are redacted from every output — what goes to an LLM and the handoff document itself. In a terminal you get a live progress bar with elapsed time and an ETA:

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

Sessions with API usage data also get a Tokens line in the header (input incl. cache / output). Map-reduce chunks run 4-way parallel on API providers (claude/openai/gemini); claude-cli and ollama stay sequential by design.

Config (optional)

Put defaults you always use in ~/.config/claude-handoff/config.json (CLI flags always win; CLAUDE_HANDOFF_CONFIG overrides the path):

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

Allowed keys: llm, model, fit, output, include_tools, include_sidechains, max_chars, anonymize, focus. Security switches (no_redact) are deliberately not configurable — weakening redaction must be an explicit per-run choice. A broken config warns and is ignored, never fatal.

MCP server

Any MCP client (Claude Desktop, Claude Code, …) can pull handoffs directly:

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

Tools: list_sessions (what's on this machine) and handoff (build the document for a session by name/project/path; pass anonymize for a shareable version). Deterministic by default — an MCP client can only trigger LLM summaries when you start the server with --allow-llm.

Roadmap

• Gemini exports as input (Google Takeout ships HTML only — bring a real, redacted export to build against)
• Session chains: auto-detect /compact-continued sessions and offer to merge the lineage (--follow)
• Opt-in LLM summaries over MCP (--mcp --allow-llm)

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

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