handoff

A clean bridge between Claude Code sessions.

Long Claude Code sessions rot: context fills up, the model starts forgetting decisions, re-trying approaches that already failed, and describing files that no longer look like that. Starting a fresh session fixes the rot — but throws away everything the old session learned.

handoff writes a verified HANDOFF.md at your project root so the next session picks up exactly where this one left off, without repeating your dead ends.

A messy 3-hour session → /handoff → one clean file the next session resumes from.

---

Install

git clone https://github.com/ostikwhy-blip/claude-code-handoff-skill.git
cp -r claude-code-handoff-skill ~/.claude/skills/handoff

Start a new Claude Code session — done. No dependencies, no external APIs, no configuration.

Install for a single project instead

cp -r claude-code-handoff-skill your-project/.claude/skills/handoff

Use

End of a session (or when it starts feeling off):

/handoff

Claude verifies the actual state of your repo, then writes HANDOFF.md.

Start of the next session:

resume from the handoff

Claude reads the file, re-checks it against the current repo, surfaces open questions, confirms the plan with you — then continues the work, already knowing what failed last time.

That's the whole workflow. Two commands.

Why not just ask Claude to "summarize the session"?

Because that summary is written from a degraded model's memory, at exactly the moment that memory is least reliable. You get confident fiction: tests that "pass" but were never re-run, file descriptions that are twenty edits stale, hallucinated progress.

handoff is built around one rule: nothing goes in the file from memory alone.

Before writing a single line, Claude:

1. Runs git status, git log, git diff to reconstruct what actually changed — not what it believes changed
2. Re-reads every file the handoff will mention (a file that isn't where memory says is a caught hallucination, and gets corrected)
3. Re-runs your tests — "tests pass" is only written from output produced during the handoff itself

Every claim in the resulting file is tagged:

Tag	Meaning
[V]	Verified against the repo during this handoff — trust it
[?]	Recalled from memory, not re-checked — treat as a lead

When the next session resumes, it re-verifies the [V] claims against the current repo and reports any drift explicitly. Verification on both ends of the bridge.

What goes in the file

HANDOFF.md is capped at ~250–400 lines — long enough to carry what matters, short enough that a fresh session can actually absorb it. It covers:

• Current goal and verified state — the actual state, not the intended one
• Decisions made and why — so they don't get relitigated
• Failed approaches and exactly why they failed — the single most valuable section. This is the knowledge a fresh session cannot reconstruct on its own, and the reason this skill exists
• Known traps discovered in the codebase this session
• Ordered next steps, concrete enough to act on without re-exploring
• Open questions only you can answer

Every entry has to pass one quality gate: would a stranger with only this line avoid the mistake we made? If not, it gets a file, a line number, and a reason — or it gets cut.