The Rollout
The handover problem: agent sessions end, projects don't
A coding agent session is bounded by its context window; a project is not. On the repository this blog ships from, the last two months of work spans well over a hundred agent sessions across two different agents. Every one of those sessions started from zero. Whatever the previous session knew — which approach was rejected and why, what was left half-done, which test is flaky for an unrelated reason — was gone unless someone wrote it down somewhere the next session would look.
That is the handover problem. It is the agentic version of shift change at a hospital, and the industry mostly pretends it doesn’t exist. New sessions re-derive context by re-reading the codebase, which costs tokens and time, and worse, re-derivation recovers facts but not decisions. The code shows what it is; it does not show the two designs that were tried and abandoned on Tuesday.
What actually carries state today
There are four places session-to-session state can live, and they are not interchangeable.
Git history carries what changed and, with disciplined commit messages, why. It carries nothing about work in progress, rejected alternatives, or intent. It is the official record, written after the fact, by the winner.
Transcripts carry everything, which is their problem. The full record of a working session on our machines averages hundreds of events per user message; the signal about “where we left off” is diffused across megabytes. Transcripts are for audit and search (that is what Agent Sessions is for), not for briefing the next shift.
Built-in memory features (CLAUDE.md auto-memory, agent memory stores) carry durable preferences and hard-won facts well. They are the wrong shape for project state: memory is organized by topic and persists indefinitely, while project state is organized by time and is mostly obsolete in a week. Writing “task 3 is half-done” into long-term memory is how you get haunted by it in August.
The handover file carries exactly the shift-change payload: current state, open decisions, next steps. It is the only one of the four that is written for the next session, at the moment the context still exists.
The pattern
What we run in production is one file at the repo root, RepoHandover.md,
append-only, newest entry first, each entry dated and written at the end of
a working session. Three sections, no more:
The entry format matters less than the discipline around it. Ours:
- State: what is done, what is half-done, what is verified vs merely written. “Code-complete, QA pending” is a state; “made progress” is not.
- Decisions: choices made and the reason, especially rejected paths. This is the section git cannot give you. “Hover-resize approach rejected; made jumping worse; next attempt must start with runtime tracing” saves the next session a day.
- Next: the first three things the next session should do, in order.
Then one line in the repo’s agent instructions file: before starting work, read the newest entry. Both major agents honor that reliably, and a session that starts with the briefing skips the archaeology.
Two rules keep it working. Entries are written at session end, when the context is still hot; a handover reconstructed the next morning is fiction with good intentions. And the file is a log, not a wiki: nobody edits old entries, they only supersede them. When an entry stops being true, the new entry says so.
Why not just resume the session?
Resume features are real and improving, and they solve a different problem. Resuming reopens one conversation with its old context; it does not brief a different session, a different agent, or a teammate. It also drags the whole transcript back in, including the parts that were wrong. A handover entry is small on purpose: it is the distillation the resumed transcript never got.
The honest cost of the pattern is that it takes two minutes at the end of a session, which is exactly when nobody wants to spend two minutes. Automate the nudge if you can (a session-end hook that drafts the entry works well; the agent writes a decent first draft of its own shift report). The payoff compounds: on this repo, the handover file plus instructions file is now the de facto onboarding document, and it cost nothing beyond the discipline.
Session transcripts remain the ground truth underneath all of this. When a handover entry says “we rejected the geometry redesign,” the transcript is where the details live, searchable months later. That layering — terse briefing on top, full record below — is the whole system, and each layer is bad at the other’s job.