What a handoff actually captures
A session ends with a lot of value sitting only in the conversation: the decisions you reached, the dead ends you ruled out, the thing you were halfway through. When that context window closes, all of it is gone unless you wrote it down. A handoff is the act of writing it down - deliberately, in a form the next session can trust.
A good handoff captures three things, and only three:
- The decisions made - what you chose and, briefly, why, so a successor does not relitigate a question you already settled.
- What is done and verified - not what you intended to do, but what is actually finished and confirmed on disk.
- The single next move - one concrete action to take first, so the next session starts working instead of orienting.
Notice what is missing: a transcript of everything that happened. A handoff is a summary of state, not a log. The next session does not need the journey - it needs the position.
The discipline that makes it trustworthy: verify every “done”
The single most important rule of a handoff is this: verify every claim against what is actually on disk before you write it. It is easy to record “the API route is done” because you remember writing it - and easy to be wrong, because a later edit broke it, or you never saved the file, or the test that would have caught it was never run.
This matters more than it sounds, because errors in a handoff compound. If you write “done” for something that is half-finished, the next session boots on an inverted assumption - it builds on top of work that is not there, and you do not discover the gap until much later, with more on top of it. A handoff that says “done” without checking is worse than no handoff, because it actively misleads. So a real handoff re-reads the files, re-runs the checks, and only then records what is true. This is the same honesty that good Claude Code best practices demand everywhere else: verified, not “should work.”
Trigger it at a seam, not on a threshold
A handoff should be user-triggered at a clean seam - a natural stopping point where the work is in a coherent state. You call it when you decide the session is wrapping, or when you have finished a logical chunk and want to bank the progress before moving on.
It should not fire automatically when the context window gets full. That is a tempting idea and a bad one: a threshold-triggered handoff lands in the middle of half-done work, with files in an inconsistent state, and captures a snapshot that is not actually safe to resume from. The context size is a fact about the machine; the seam is a judgment about the work. You hold that judgment, so you call the handoff. Treating context pressure as the trigger is an anti-pattern - it produces handoffs at exactly the moments least worth handing off.
Why this beats a generic memory plugin
The obvious alternative is a memory plugin: some service that quietly embeds your conversation into a vector store and retrieves “relevant” chunks later. On the surface it promises the same thing - continuity across sessions - but it is a different mechanism with different failure modes.
- It is reasoned, not scraped. A handoff is something you chose to record because it is true and load-bearing. A vector store keeps whatever happened to be said, including the wrong turns and the things you later reversed.
- It is verified, not assumed. The “done” claims in a handoff were checked against disk. Retrieved memory has no notion of whether a remembered fact is still true.
- It lives in the repo, not in an opaque store. The state file is a plain document you can read, diff, edit, and commit. You can see exactly what the next session will boot on - and fix it if it is wrong. An embedding you cannot inspect gives you neither.
This is why a handoff belongs in your project setup rather than as a plugin bolted on afterward. It is part of how you do context management - a deliberate practice of carrying real, checked state forward - not a black box you hope retrieved the right thing.
How claudesetup fits
claudesetup ships the gated handoff as part of the foundation it scaffolds in one command: a place for durable state to live in the repo, the convention of triggering it at a seam, and the discipline of verifying every “done” against disk before it is written. You get the practice wired in from commit one - so the next session boots on state you can actually trust, and you own the file it reads.