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.

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:

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.

Old handoffs aren't deleted — they're archived to .handoffs/, and still-relevant dead ends are carried forward automatically.

How it compares

• Not a background memory. Ambient memory tools work invisibly; you never see what gets passed along. HANDOFF.md is a plain file you can read, edit, and commit. If Claude got something wrong, you fix it before it poisons the next session.
• Not log archaeology. Tools that search past session logs dig through raw history after the fact. A handoff is a deliberate, curated, verified artifact written at the moment of handover.
• Not a lossy summary. Summaries keep what sounds important. A handoff keeps what's expensive to rediscover — above all, the dead ends.

Bonus: it catches degradation early

If Claude notices symptoms of its own context rot mid-session — contradicting an earlier decision, re-deriving something already settled — it suggests a handoff in one sentence and waits for your confirmation. It never runs automatically.

Repo layout

handoff/
├── SKILL.md                    # the skill definition
└── assets/
    └── HANDOFF.template.md     # the structure every handoff follows

Read SKILL.md to see exactly what Claude is instructed to do — including the list of rationalizations it's told to refuse ("I remember the session clearly, no need to re-verify" → verify anyway).

Contributing

Issues and PRs welcome — especially reports of how it handles sessions that went badly. That's the case it's built for.

License

MIT