Claude Handoff

claude-handoff

Turn any Claude Code session — even a crashed one — into a clean `handoff.md` another AI can continue from. And give Claude Code permanent project memory, distilled from your own history.

chf

That's it. Your latest session becomes handoff.md: the conversation without the noise, the files that changed, the commands that ran — opening with instructions to the receiving assistant, so you can paste it straight into Gemini, GPT, claude.ai, or a fresh Claude Code session with zero extra prompting.

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 — and, since it can read your *entire* history, a project memory brief too.

• 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 — what this is, where things stand, decisions, fixes, conventions, and an ordered resume plan of open threads, every claim citing its session; --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. --anonymize goes further for public sharing.

---

Prerequisites

No third-party Python packages, ever — everything runs on the standard library.

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

Installing the package gives you two identical commands: claude-handoff and the short alias `chf`. Tab completion:

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

---

60 seconds: pick your situation

A session crashed, hit the usage limit, or you closed the terminal:

chf -o clipboard

…then paste into claude.ai, ChatGPT, Gemini — or a fresh claude session. Works on any old session; nothing needed to be installed *before* the crash.

Moving work from Claude Code to another model:

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

"Which session was it where we talked about CORS?"

chf --list --grep "CORS"           # every match, with a 🔍 context preview

chf --grep "CORS" # or export the newest match directly

Give Claude Code permanent memory of this project:

chf --brief --llm claude-cli       # distill ALL sessions → one cited brief

chf --install-brief-hook # every new session starts knowing it

A real summary instead of the transcript (goal / decisions / state / next):

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

A claude.ai or ChatGPT web chat instead of a terminal session:

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

chf conversations.json --name "webhook bug"

---

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 to ~/.claude/briefs/ .md:

• a factual session timeline + most-touched files (deterministic, free);
• with --llm, a distilled memory that opens with *what this is* (product, stack, current state) and *where things stand* (done / in flight / not started), then decisions with their why, fixed bugs, conventions — and *open threads* as an ordered resume plan, each with its concrete next action and a [in flight] / [blocked] / [not started] tag. Every bullet cites the session id it came from (chf --name opens the source).

Per-session notes are cached, so refreshing after new sessions only pays for the new ones — and a monster session (beyond ~120k chars) is map-reduced *inside* the note, so the memory path never truncates: nothing is silently dropped, at any size.

You can also curate what feeds the memory: --exclude leaves a session out (a duplicate, an experiment — bare --exclude opens a numbered picker that remembers: the stored exclusions arrive pre-selected with ✗ and typed numbers toggle, so you edit the set instead of re-picking it), and --keep first:2,last:20 windows a huge history to the founding sessions plus a sliding recent window. Both are sticky — stored in the brief's stamp, so hooks and later refreshes keep honoring them until you change them (--exclude none, --keep all). And chf --brief -o clipboard ships the current brief — distillation included — straight to the clipboard, one paste away from handing your project memory to another model.

The brief also goes beyond the project store: chf --brief --grep X -o - distills a thematic memory (only the sessions that talked about X), and chf conversations.json --brief -o brief.md builds standing memory from a claude.ai or ChatGPT export — every conversation, cited by its id. Both are exports by design (explicit -o only) so they never overwrite the standing brief.

Running graphify? The two tools compose in both directions, zero config: chf --brief -o graphify files the current memory into raw/ — one evolving project-memory.md that the next /graphify --update links into the code's knowledge graph — and once graphify-out/graph.json exists, every brief gains a free ## Code map (communities, hub concepts, cross-community bridges:, labeled flows:) so new sessions know the code's *structure*, not just its history. The in-project copies (raw/project-memory.md, optional root BRIEF.md) refresh on every brief write — strictly refresh-only, hooks never create files. The full loop lives in [docs/GUIDE.md](docs/GUIDE.md).

chf --install-brief-hook

installs two hooks: SessionStart injects the brief as context (Claude starts already knowing your project — re-injected after /compact too), SessionEnd auto-refreshes the factual part for free. No LLM ever runs from a hook; the distilled part refreshes only when you say so. The brief carries a freshness stamp, and when newer sessions or commits exist the file and the injection don't just warn — they list them (session titles, commit subjects), so a fresh session sees *what* changed, not merely that something did. Fully local; redaction applies as everywhere.

→ Step-by-step mechanics, the honest cost table, and a full day-with-it walkthrough: [docs/GUIDE.md](docs/GUIDE.md).

Make it automatic

chf --install-hook                 # SessionEnd + PreCompact → handoff to ~/.claude/handoffs/

chf --install-brief-hook # SessionStart/End + PreCompact → project memory (above) chf --install-skill # /claude-handoff skill → Claude Code drives chf correctly

PreCompact matters: right before Claude Code compacts a long session's context, both hooks snapshot state — the handoff preserves detail that compaction is about to squeeze away, and the brief skeleton stays fresh mid-session.

Both edit ~/.claude/settings.json non-destructively, are idempotent, and have matching --uninstall-* flags. Hook failures never break the host session, and hooks never trigger LLM calls or create files on their own.

The third one is for Claude itself: --install-skill puts a /claude-handoff skill into ~/.claude/skills/ (plus its trigger in ~/.claude/CLAUDE.md), so Claude Code knows the tool's grammar instead of guessing — which session bare chf picks from inside a live session, claude-cli (subscription) vs claude (API key), --fit for token budgets, no interactive pickers from an agent shell. Idempotent, respects a hand-written section, and --uninstall-skill removes both pieces without touching anything else in either file.

---

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, 2 assistant replies, 4 tool calls

Files created / modified

• 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

_Condensed digest, every turn capped — verbatim messages with --full, a real summary with --llm._

• 🧑 User: the login breaks on unicode passwords…
• 🤖 Assistant: Found it — ascii encoding. Changed to utf-8, tests pass. _[4 tool calls]_
• 🔔 Agent "Update the docs" finished

Every turn is there, condensed to its lead — it's a summarize tool, not an exporter. --full switches to classic verbatim messages, and --llm replaces the digest with a real summary that read *everything*.

Common commands

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