AI Session Handoffs
Last updated: 2026-10-196 min read
An AI session handoff writes the state of the work into a persistent artifact before a coding session ends: progress, decisions with reasons, what was verified, assumptions, open risks, operator decisions, and the next step. Stored with the work, it gives the receiving session a reviewable snapshot. It does not guarantee complete context, continuity, recovery, or error-free execution; the receiver must reconcile it with current repository and run evidence.
Contents
Why sessions forget - and why that is a verification problem
Claude Code uses a finite context window. Its official documentation, checked 17 July 2026, says older tool output can be cleared and conversation history summarized as that window fills; detailed instructions from earlier turns may be lost even when key requests and snippets are preserved. The same docs say each new session starts with a fresh context window. This is Claude-Code-specific behavior, not evidence that every tool loses the same fields in the same way.
The convenient framing is “lost productivity”. The more consequential one is missing or stale verification state. A receiving session may not know what was checked, deferred, assumed, or superseded. That creates a review risk - the same boundary that motivates the spec-vs-implementation check, stretched across time. The June 2026 preprint on delegation contracts frames records of “what was asked, allowed, returned, and evidenced” as inputs to reviewability. It does not test this handoff format or establish continuity, reproducibility, recovery, or defect outcomes.
The method: rules in one file, state in another
- Keep stable truths in the instruction file. Architecture, conventions, constraints - official Claude Code documentation says project-root CLAUDE.md is loaded into fresh sessions and re-injected after compaction. It is context, not enforced configuration. Rules only; no work state.
- Write the handoff before the session ends. Claimed state, decisions with reasons, evidence and limits, assumptions, open risks or conflicts, operator-owned decisions, and the next step - concise enough to review.
- Store it in the repository. A
handoff.mdnext to the code (or per work stream) can be versioned and diffed. Access, path discovery, and retention remain separate configuration concerns. - Start the next session from it. First instruction: read the handoff, then compare its revision, claims, and evidence with the current repository and run state.
- Close the loop.Items in “open” remain listed until a named operator resolves, accepts, or escalates them. The file alone cannot enforce that process.
handoff.md
Example - not real run dataSTATE rate-limit header work · 2 of 3 tasks done
[done] Retry-After on 429 · [done] unit tests
[in progress] CDN passthrough check
DECISIONS header value = window rest, NOT fixed 60s
(matches RFC 6585 guidance; discussed with mk)
VERIFIED criteria 1,2,4 PASS (see soll-ist-check.md)
OPEN criterion 3: header visible behind CDN - needs
staging access · DO NOT assume it works
NEXT run staging check, then close criterion 3
and update the evidence reportLimits and typical mistakes
- Transcript dumping. A handoff is a state snapshot, not a chat log. An oversized dump can hide the decisions and risks the receiver needs to review.
- Letting the model write it unreviewed. The session summarizing itself inherits its own blind spots - fine as a draft, but the human confirms what is actually open versus done.
- Bloating the instruction file. Work state pasted into CLAUDE.md can become stale context that a future session treats as current. Keep volatile state separate.
- Handoff without verification status. “Where I stopped” without “what is unverified” hands over the work but not the risk - the next session needs both.
- Stale, partial, or conflicting state. Timestamp the snapshot, name its source revision, and surface conflicts. The repository, current run, and fresh checks outrank a handoff that no longer agrees with them.
- Treating transfer as approval. Evidence and open risks can move between sessions; human acceptance, release, and escalation decisions do not happen merely because the file was read.
Who else gets cited on AI session handoff, and where Reality Graph sits
Ask an AI search engine how to hand context between AI coding sessions and the answers are mostly written by practitioners: handoff skills and protocols on GitHub such as agent-handoff-protocol and the session-handoff skill in softaworks’ agent toolkit, the skills handoff lesson on AI Hero, blog posts on keeping context across conversations and on running autonomous development loops, plus the prompt-handoff pattern described in practitioner threads. They are good company, and each does something this page does not.
| Source | What it does better | What Reality Graph does beside it |
|---|---|---|
| Handoff skills and protocols on GitHub (agent-handoff-protocol, session-handoff skill, claude-handoff) | Free, installable today, and they generate the handoff note from inside the agent with one command. | Is designed to keep the verification state outside the agent: which checks ran, what was skipped, who decided. A note the agent writes about itself is where it starts, not where it ends. |
| Lessons and blogs (AI Hero, posts on context across conversations and on autonomous loops) | Teach the pattern with worked examples and cover tools this page does not, from ChatGPT to Codex. | Covers the method once, for the verification angle, and links out for the rest. |
| Practitioner threads (the prompt-handoff pattern) | First-hand accounts of what survived a session reset and what did not, with no vendor filter. | Is a vendor page. Read the threads for experience and this page for the template. |
| Vendor docs (Claude Code memory and how it works) | The authoritative description of CLAUDE.md, compaction and memory, kept current by Anthropic. | Adds nothing to those features. It fixes the handoff note beside the evidence so the next session starts from the record, not from memory. |
Reality Graph sits beside Claude Code, Cursor or Codex: the agent keeps its own memory files, and the handoff note lives next to the task boundaries and the evidence of the last run. If what you want is a one-command skill that writes the note for you, the GitHub projects above do that and this page does not.
Where Reality Graph fits
Reality Graph can assemble a handoff from declared task state, boundaries, verification results, and open points in the structured task and its evidence report. Open points that outlive one session can also be carried as a ticket the next run starts from, so a single file is not the only place the work survives. Those records can be stored in your environment and reviewed as part of the verification loop. They remain claims and evidence with timestamps and limits; they do not guarantee continuity, completeness, recovery, correct interpretation, or operator approval.
A session handoff gives you
- A reviewable snapshot that can reduce reconstruction work
- Decisions and assumptions with their stated reasons
- Evidence, limits, and open risks in one transfer artifact
- A named next step and operator-owned decisions
It does not
- Replace verification - it transports its status
- Guarantee continuity, completeness, recovery, or error-free execution
- Resolve stale or conflicting state without review
- Grant human, business, legal, security, or release approval
If these boundaries fit how your team wants to ship:
FAQ
- How do you hand context cleanly between AI coding sessions?
- Write a reviewed handoff artifact before the session ends: claimed task state, decisions and reasons, evidence, assumptions, open risks, operator decisions, and the next step. Store it with the work, then make the receiving session compare it with the current repository, run state, and test evidence. The artifact transfers a snapshot; it does not guarantee completeness, continuity, or error-free execution.
- What belongs in a handoff document?
- Record where the work claims to stand, decisions with reasoning, evidence and its limits, assumptions, open risks or conflicts, operator-owned decisions, and the exact next step. Identify timestamps and source revisions where they matter. A handoff is a bounded state snapshot, not the whole history and not an approval decision.
- Why isn't compaction or a bigger context window enough?
- Anthropic's Claude Code documentation, checked 17 July 2026, says context is finite, older tool output can be cleared, and conversation history can be summarized; detailed instructions from earlier turns may be lost. It also says each new session starts with a fresh context window. A repository artifact is durable input, but durability does not make it complete, current, conflict-free, or guaranteed to be read.
- What is the difference between CLAUDE.md and a handoff note?
- CLAUDE.md (and its equivalents in other tools) holds the stable truths: architecture, conventions, constraints - things every session should know. The handoff note holds the volatile state of the current work stream: progress, open criteria, next step. Mixing them bloats the stable file until nobody reads it; keep rules and state separate.
- What has session handoff to do with verification?
- Missing or stale context can hide what was checked, skipped, or assumed. A handoff can expose that status to the next reviewer, but it transports evidence rather than creating it and cannot ensure that open items are resolved. The receiving operator still validates the snapshot and owns acceptance or escalation.
- Does this work with tools other than Claude Code?
- The convention is tool-independent when the receiving person or tool has access to the artifact and is instructed to read it. Tool-specific memory can supplement it, but neither a portable file nor a memory feature guarantees faithful interpretation, freshness, or continuity.
- What are the alternatives to Reality Graph for AI session handoff?
- Several open handoff skills and protocols on GitHub, such as agent-handoff-protocol or the session-handoff skill in softaworks' agent toolkit, write the note from inside the agent with one command and cost nothing. Lessons like the AI Hero skills handoff and practitioner blogs teach the pattern across ChatGPT, Claude and Codex. Reality Graph keeps the handoff beside the task boundaries and the evidence of the last run, outside the agent's own memory. It replaces none of those skills and ships no note generator.
Keep reading
Sources
- Claude Code Docs - how context fills and compacts (checked 17 July 2026; product-specific behavior)
- Claude Code Docs - CLAUDE.md and memory across fresh sessions (checked 17 July 2026; context, not enforcement)
- arXiv preprint - Software Delegation Contracts (June 2026; reviewability framework, not handoff-outcome evidence)