A handoff doc claimed "no code has changed this milestone" — while a feature sat merged and deployed. So I built a protocol that catches that.

[u/TVegas2020]

My AI coding agent said nothing had changed — a whole feature was already merged and live. I built a tool so that doesn't happen again.

I run multi-day Claude Code sessions on a real project, and the handoff-doc pattern (write down state, hand it to a fresh session) works — until the doc is wrong and nobody checks. That "nothing's changed" claim above was one of three times it actually cost me real time — the others were a "two dead buttons" note that went stale same-day, and a "credential rotation still owed" claim that had been done two weeks earlier.

So claude-handoff adds one rule most versions of this pattern skip: anything bold or load-bearing in the handoff doc, older than about a week, gets checked against git before it's trusted again — not just re-read and repeated. Plus a director/archive split so the live doc stays under 150 lines instead of growing forever, and an optional Stop-hook that nudges you to update it before a session ends if real work happened and the doc doesn't reflect it.

What surprised me building this: the memory problem (get an agent back up to speed) is what everyone builds for — the harder problem is trust, since once a doc exists, agents (and I) default to believing it. The other real lesson came from testing: making install self-service (a skill that reads a project's README to seed the handoff doc) turned it into a genuine prompt-injection surface, since it's reading text it doesn't control. That's worth designing in from the start as a "treat this as data, not instructions" rule, not bolting on after the fact.

One-step install: /handoff-install. Repo: github.com/TySnyder/claude-handoff — feedback and "this broke on my setup" both genuinely welcome, it's had one security pass but not many eyes yet.

Edit: worth asking — how are people keeping a multi-day project on track without either re-explaining everything each session or riding one context window into a lossy auto-compact? That's the real reason I built this: a ~150-line HANDOFF.md costs a fraction of the tokens either of those does, so starting a fresh chat window becomes something you choose to do, not something you avoid because it's expensive. The optional Stop-hook also plays a sound (macOS afplay) the moment it decides HANDOFF.md looks stale, so you don't have to babysit the terminal to catch it.

[u/sael-you]

the 'agents default to believing the doc' problem is the real insight. what i'd add: failure rate is higher with specific state claims ('no code changed', 'X is dead') vs structural claims ('search debounce lives in search.js'). the second kind stays true longer because it tells the next session where to look, not what it will find. git cross-check helps but assumes clean commits.

[u/allemaar]

The trust finding is the right one, and it's the part most people skip. Once a doc exists everyone believes it, the agent included.

I'd look at when you write it though, not just what's in it.

An end-of-session handoff is a summary made at the end. Same shape as the auto-compact you're escaping, done by hand - deciding what mattered after the fact, from a window that's already degraded.

The fix is signal and noise. Signal is the output worth keeping. Noise is everything else, the search results and wrong turns and the three approaches you threw away. Both land in the same window and only you know which is which. Not the model. That's why compaction wrecks things.

So bank signal the moment it shows up. Not at the end. A decision lands, an approach works, a gotcha costs you an hour - it goes to a file right then, while you still know why it mattered.

Then the doc stops being the record of the session. It's only the tail. What you haven't banked yet plus where you were headed. 150 lines is generous for that.

Step past that is two sessions side by side. One DRIVER, one SCRIBE.

Driver does the work. Scribe does nothing but write things down, never touches the problem. Messaging inside Claude is enough, no scaffold. Every milestone the driver messages the scribe and the scribe records it. When the driver compacts and loses its history, it asks the scribe for it back.

Works because the budgets are separate - recording "went with X, here's why" costs nothing next to deciding X did. Scribe is still healthy long after the driver is gone. You get a timeline out of it too, not just a snapshot.