handoff — the skill that survives context compaction and chain-links your sessions

A long coding session is a context window slowly filling up. When it gets full, the model compacts itself — and the compaction is the moment decisions get lost. The agent compresses a two-hour conversation into a summary, and the summary drops the parts that did not look important at the time: which approach was tried and rejected, why, and what the actual numbers were. Your next session starts by rediscovering all of it, sometimes by re-treading the same dead ends.

handoff (the claude-handoff project) is built specifically for this. It is a pair of Claude Code skills — /handoff and /handoffplan — that capture a structured, self-validating snapshot of your session into a file outside the context window, so a fresh session can pick up exactly where you left off. The project’s own claim, measured in controlled A/B runs on the same bug and codebase, is that a session resumed from a handoff file needs zero user intervention and traces the complete failure chain, whereas a session that just got compacted proposes a surface-level fix.

What it does

Every handoff writes a markdown file with a fixed shape:

Section	What it holds
The Goal	what is being solved and why
Where We Are	15–25 bullets of current state
What We Tried	every approach, chronological — what was tried, what happened, why it was kept or abandoned
Key Decisions	what was chosen and rejected
Evidence & Data	real numbers, not summaries
User Feedback	preferences, corrections, tone
Where We’re Going	ordered next steps
Quick Start	the exact commands the next session runs first

The project is explicit that “What We Tried” is the most valuable section: failed approaches are the most expensive thing to rediscover, and this section is the one that stops the next session from repeating them.

The process behind the file has five moves:

1. Mines the conversation with a 12-item extraction checklist — goals, approaches, failures, decisions, measurements, code analysis, user preferences.

2. Gathers external state in parallel — git log, git diff, uncommitted changes, active tasks.

3. Detects chain continuity. It finds prior handoffs in the same work stream and inherits the chain tag and a sequence number, so handoffs link across sessions:

   HANDOFF_fix-auth_2026-03-17.md  (seq 1)
       └─ HANDOFF_fix-auth_2026-03-18.md (seq 2)
           └─ HANDOFF_fix-auth_2026-03-19.md (seq 3)

   Your third session on a feature knows about the first two.

4. Validates its own output. A first write must hit a pass minimum; a second pass fills gaps toward a ceiling. This is the difference between a file that looks like a handoff and one that has been checked.

5. Adapts to context size. At 500K+ tokens it switches to a multi-pass map-reduce extraction to avoid the “lost in the middle” problem.

/handoff vs /handoffplan: both capture the session; the difference is what the next session does. /handoff is for pausing mid-work — the next session reads the brief, onboards, and explores. /handoffplan is for when research is done and you are ready to build — it also writes a phased plan with tracked tasks, dependency chains between phases, anti-goals derived from the failed approaches, rollback strategies, and success criteria tied to the real numbers from your session. Both end by giving you a ready-to-paste resume prompt.

The pain it removes

• The compaction tax. /compact fires when the context is already stuffed, and a stuffed model is a dulled one: it decides on its own what matters, and every compression loses something. A handoff is written deliberately, by a process that knows exactly which fields must survive.
• Rediscovering what was already tried. The single most common waste in a resumed session is re-running an approach that already failed. The “What We Tried” section is designed to eliminate exactly that.
• Context that does not survive the session. The file lives in your repo, outside the context window. It is a plain markdown file you can read, correct, and diff. It is not a black-box summary the model produced and you cannot inspect.
• Loss of chain of thought. Because handoffs chain by sequence number, a feature that spans three sessions keeps a continuous record instead of three orphaned summaries.

How to use it

Install both skills:

git clone https://github.com/REMvisual/claude-handoff.git
cp -r claude-handoff/skills/handoff ~/.claude/skills/
cp -r claude-handoff/skills/handoffplan ~/.claude/skills/

Verify by typing /handoff in Claude Code — it should appear in autocomplete. Usage:

/handoff       # pause mid-work: capture context, next session explores
/handoffplan   # research done: capture context + write a plan, next session executes

No arguments needed. It mines the conversation, gathers git state, validates, and hands you a paste-ready prompt:

Read `plans/handoffs/HANDOFF_fix-auth-bug_2026-03-19.md` (seq 2, PROJ-abc1)
and continue from "Where We're Going".

Paste that into a fresh session. It picks up the chain and starts working.

Two supporting pieces, both optional but worth knowing:

• Prevent skill shadowing. Without a rule, Claude may generate freeform “handoffs” when a session ends — documents that look right but skip the process. Add to CLAUDE.md: “When ending a session or saving progress, ALWAYS use the /handoff skill. NEVER generate handoff summaries without it.”
• PreCompact hook. A safety net that runs before context compaction, capturing ~50 lines of git state and active tasks, in case you reach the compaction threshold before you remember to hand off.

It also pairs with task trackers (Beads by default, or Linear / Jira / GitHub Issues) and persistent memory tools, using them as chain tags and prior-decision lookups.

Where it does not help

• Short, single-session work. If the task fits in one context window, the overhead of a structured handoff is not justified.
• It is not a substitute for writing things down as you go. The skill mines the conversation, but it can only extract what was actually said. A decision made in your head is not in the transcript.
• The file is only as good as the session it captures. A session full of half-formed explorations produces a handoff full of half-formed state. It amplifies clarity; it does not create it.
• Chain continuity depends on you keeping the handoffs in one place. Scatter them across branches or rename them and the sequence detection loses the thread.

Why this is the right shape for “memory between sessions”

The durable insight is not the file format — it is the principle: keep the things that matter in a structured form outside the context window, and pull only that back in. That is exactly what Anthropic describes as structured note-taking in its context-engineering guidance. /compact is lossy compression done by a tired model; a handoff is deliberate extraction done by a process with a checklist. The skill makes the second one a one-keypress habit.

How this article was written

Facts (install path, commands, file sections, chain model, the A/B claim) are taken from the repository’s README.md as of 2026-09-10. The A/B results are the project’s own measurement and are reported here as such, not as our independent test. The assessment of where it helps is our editorial judgment. Re-check the repository before relying on any detail — the project is young and moving.