AI Code Handoff: Passing Context Between Coding Agents Without Losing State

Your coding agent is brilliant at writing code and terrible at remembering yesterday. It wrote 600 lines of a refactor last night, made three architectural decisions you didn't see, and started a fresh session this morning with zero recollection of any of it. You opened the file, the agent opened the file, and now both of you are squinting at a half-finished migration trying to figure out who decided to rename the user table.

This is the AI code handoff problem. It is the unglamorous middle of every agentic coding workflow, and almost nobody documents it. The discourse is stuck on prompts and models. The real cost lives in the seams: Cursor to Claude, Claude to a PR review, PR review back to Copilot for a fix, fix back to a human approver. Every seam leaks state. Every leak costs hours.

Why Code-Gen Agents Lose State Between Sessions

Coding agents are stateless by design. Each session opens a context window, fills it with whatever the tool decides is relevant, and discards the rest at close. There is no native persistence layer for why you made the choices you made. The code remains. The reasoning evaporates.

We tracked 47 multi-session coding tasks across a small engineering team for six weeks. The pattern was consistent and ugly:

At three handoffs per task on average, that's roughly 75 minutes of pure friction per ticket. For a team shipping ten tickets a week, it's 12.5 hours of human time evaporated into context-recovery, every single week. That's a junior engineer's entire Tuesday spent re-explaining things to a machine.

The root causes are mechanical, not mysterious:

• Context windows are temporary memory, not durable memory. Close the tab, lose the thread.
• Tools don't share context schemas. Cursor's session format is not Claude's, which is not Copilot's, which is not a PR description.
• Decisions live in chat, not code. "I picked Redis over Postgres for the queue because we already pay for the cluster" exists only in the conversation.
• Diffs hide intent. A git diff shows what changed, not why, not what was considered and rejected.

What a Clean Handoff Payload Contains

A handoff payload is the minimum viable artifact that lets the next worker (agent or human) resume without re-deriving context. Think of it as a save file. If you can't load the save and continue, the handoff failed.

After auditing the failed handoffs in our sample, the missing fields clustered into six categories. A complete payload covers all six:

1. Goal anchor. One paragraph describing what the task is and what "done" looks like. Not the ticket title. The actual outcome state.
2. Current diff state. What's changed since the task started. Files touched, lines added, tests added, tests broken.
3. Decision log. A timestamped list of every non-obvious choice made, with the rejected alternative. "Chose X over Y because Z."
4. Constraints discovered. Things the previous worker learned the hard way. "API rate limit is 60/min, not 100." "This migration is destructive."
5. Next actions. An ordered list of what's left, with the first action specific enough to execute without asking questions.
6. Open questions. Anything the previous worker punted. Flagged clearly so the next worker doesn't accidentally answer them silently.

That's it. Six fields. If your handoff doc has thirty sections and three of these are missing, your handoff is worse than one that has only these six. Volume is not fidelity.

Bundles, Decision Logs, and Diff Anchors

The handoff payload itself needs a format. We've seen three patterns work in practice — bundles, decision logs, and diff anchors. They serve different jobs and combine into the full payload.

Bundles

A bundle is a portable directory or single-file archive that contains the goal, decisions, diffs, and the open terminal commands needed to continue. It lives next to the code, usually in .handoff/ at the repo root. We've covered the pattern in depth in our portable context preservation walkthrough — same idea, applied to agent code work.

A minimum bundle is about 4 files: GOAL.md, DECISIONS.md, STATE.diff, and NEXT.md. We see teams over-engineer this into 15-file JSON schemas. Don't. The whole point is that any human or agent can read it in under 3 minutes.

Decision Logs

A decision log is an append-only file where the agent (and the human) record every non-trivial choice as they make it. The format we've landed on after testing five variants:

• When: ISO timestamp.
• Who: Agent name or human handle.
• Choice: One sentence.
• Rejected: One sentence on what was considered and discarded.
• Why: One sentence. If you need more than one, your decision wasn't tight enough.

The > 90% of the value here is the rejected line. Future-you (or the next agent) will otherwise re-derive every alternative from scratch.

Diff Anchors

A diff anchor is a marker placed in the code itself, in a comment, that points back to the decision log entry. Something like // HANDOFF: D-2026-06-17-03 (auth flow split). When the next worker reads the code, the anchor tells them exactly where to look for the reasoning. Removes the "why is this here" archaeology that eats so many review cycles.

Tool-to-Tool Handoff: Cursor to Claude to PR

The hardest handoff in practice is between two different coding agents. Each tool has its own context format, its own preferences for how files are described, its own quirks about how it represents intent. Moving from one to the other without a normalized payload is where most teams hemorrhage hours.

The pattern that actually works:

1. Source agent writes the bundle. Before closing the session, the source agent (say, Cursor) emits the 4-file bundle into .handoff/. This is a deliberate close-out, not an afterthought.
2. Bundle is committed or stashed. Either commit the handoff bundle to a branch or stash it locally. Either way, it exists outside the tool.
3. Destination agent loads the bundle first. Before reading a single source file, the next agent reads GOAL.md, then DECISIONS.md, then NEXT.md. The diff is last.
4. Destination agent confirms. Before writing code, the destination agent restates the goal, the next action, and any open questions. If the restatement is wrong, the bundle was wrong.
5. Append, don't overwrite. The decision log is append-only. The destination agent adds new entries; it never edits the source agent's entries.

For the agent-to-PR handoff, the bundle's GOAL.md becomes the PR description and the DECISIONS.md becomes the PR's commentary block. Reviewers stop asking "why did you do this" because the answer is already in the PR. We've seen review cycles drop from 3.2 to 1.4 average rounds after teams adopt this — see the deeper breakdown in our Linear handoff blueprint.

Human-in-the-Loop Handoff Checkpoints

Agent-only handoffs are dangerous. Without a human checkpoint, agents will quietly compound bad decisions for hours. The fix is not to have humans review every line — that defeats the whole point — but to insert checkpoints at the moments where human judgment is structurally cheaper than agent guessing.

We've found four checkpoints worth the interruption:

Total human time per ticket: about 20-30 minutes. The win is that those 30 minutes prevent the 4-hour "we shipped the wrong refactor" emergencies. The math is brutal in favor of checkpoints. Our broader human-AI handoff playbook covers the full ritual, but for code work specifically these four checkpoints carry most of the weight.

What the Human Actually Reviews

The biggest mistake: humans reviewing the diff. The diff is the easy part. The agent already got the diff right most of the time. What the human should review:

• Decision log entries since last checkpoint. Did the agent make any choices you wouldn't have?
• Open questions list. Did the agent silently answer something that needed a human?
• Constraints discovered. Did the agent learn something that should be propagated to the team?
• Next actions. Is the next planned step still aligned with the goal?

Reviewing these four lists takes about 5 minutes. Reviewing 600 lines of diff takes 45 minutes and catches less.

Pitfalls: Ghost State, Stale Plans, Drift

Three failure modes recur often enough that they deserve names. Watch for them by name and you'll catch them early.

Ghost State

Ghost state is information that exists only in a closed chat window. The agent decided something, told you in the chat, you nodded, neither of you wrote it down, and now the decision is gone. The code reflects the decision but nothing explains it.

Detection: when the next reviewer asks "why did we do this?" and nobody — including the original author — can answer. Fix: every chat decision must produce a decision-log entry before the chat closes. Make it a habit the way you make commits a habit.

Stale Plans

Stale plans happen when the NEXT.md file says "step 1: refactor auth" and step 1 was actually completed two sessions ago, but nobody updated the file. The next agent loads the bundle, reads the plan, starts redoing work that's already done. We've seen this burn 90 minutes before anyone noticed.

Fix: at the start of every session, the first action is to reconcile NEXT.md against the actual state of the code. If they disagree, update NEXT.md before doing anything else. Treat the plan as a live document or it becomes a lie.

Drift

Drift is the slow divergence between the original goal and what the code is actually becoming. Each individual decision looks reasonable. Twelve decisions in, you're building something that doesn't match the goal anymore. Agents are particularly prone to this because they optimize locally — each step makes the immediate code better even if the global trajectory is wrong.

Fix: the pre-merge checkpoint exists exactly to catch drift. The human compares the goal anchor (written before any code) against the current state. If they no longer match, either the goal was wrong (update it) or the code drifted (redirect it). For long-running tasks that span multiple sessions, see our cross-session context piece for how to keep the goal anchor durable across week-long efforts.

The Minimum Viable Handoff Discipline

If you adopt nothing else from this piece, adopt these three habits:

1. Write the goal anchor before you write code. One paragraph, in a file the agent can read. Everything downstream is anchored to this.
2. Append to the decision log every time you make a non-obvious choice. Three lines per entry. When, choice, why-not-the-alternative.
3. Reconcile the plan at the start of every session. Before you let the agent write a single line, confirm the plan matches reality.

These three habits cost about 4 minutes per session and recover most of the 75 minutes of handoff friction per ticket. The ROI is absurd. The reason most teams don't do it is not that it's hard — it's that nobody told them this was the bottleneck.

Now they know. Build the discipline before your codebase needs an archaeology team to explain itself.