--- title: "The handoff file: every session rewrites it, none appends" url: "https://toddpaulbrownjr.com/writing/the-handoff-file/" author: "Todd Paul Brown Jr." description: "Agents forget between sessions. A single handoff file, rewritten not appended, plus a stand-up and wind-down ritual keeps long projects coherent." kind: "article" updated: "2026-09-26T02:50:42+00:00" --- # The handoff file: every session rewrites it, none appends On 20 March 2026, I ran a dedicated refinement audit on the creature-battler game. The agent found and fixed four production bugs, including one that unconditionally purged every creature in the player's collection on launch. That DEV ONLY function had shipped live. The agent had written it. I had approved it. Nobody caught it until an audit specifically told the agent to look for problems like that. The reason nobody caught it is simple: the agent that wrote the code had no context from the session that planned the creature system, and I hadn't given it one. It wrote what it thought made sense, passed its tests, and stopped. The session ended. The next session started fresh, with no knowledge of the previous one's decisions, constraints or risks. I opened the repo three days later, and the game was eating save files. This was not the agent's fault. It was mine. I hadn't built a system that survived the session boundary. ## Why agents forget Claude Code, ChatGPT and the rest start every session from scratch. They read what you give them — a project brief, a README, the code itself — but they do not inherit memory from the session you ran yesterday. If the last session decided that creature stats must never exceed 255, and you do not write that rule into a file the next session reads, the next session does not know it. Appending to a log file does not solve this. Logs accumulate; they do not summarise. By session fifteen, the agent is reading thirty pages of transcript to find the one paragraph that matters, and it misses it half the time. I tried that on an early LEGION attempt in April 2025. Agents lost work in wiped Docker containers, edited the UI into black-on-black text, and ignored the handbook until I forced it into the default prompt. The problem is not that agents cannot read files. The problem is that sessions do not inherit decisions. ## The rule that fixed it One file. One handoff. Rewritten, never appended, at the end of every session. I codified it in the creature-battler on 20 March 2026, then in Milkman in August 2026, and it is now the entry point for every project I run with an agent. The file is called `SESSION.md` or `SESSION_HANDOFF.md`, and it contains exactly what the next session needs to pick up where this one left off: what was accomplished, what failed, what the current plan is, and what risks or constraints the next session must respect. The agent writes it. I review it. The next session opens that file first. About the same time — March 2025 — OpenAI's Responses API launch cited "customers struggling with custom orchestration logic," and Google Cloud's blog described "agentic orchestration" as handling state the model alone could not. The problem I was fixing in my own repo was the problem the harness papers would later describe: agents need structure around them, or they lose their work. ## The ritual The handoff file is part of a three-step ritual I run on every session: 1. **Stand-up.** The session opens by reading `SESSION.md`, the technical design doc and the risk register. I give it a goal for this session — one goal, stated plainly — and it confirms what it read. 2. **Execution.** The agent writes code, writes tests, runs the tests, writes documentation. I interrupt only to approve a commit or redirect a plan that has drifted. 3. **Wind-down.** The session rewrites `SESSION.md` with what it accomplished, what it tried and failed, what the next session should do, and any new risks it discovered. I review the handoff and approve the commit. The stand-up and wind-down are not optional. They are the structure that keeps the project coherent across sessions that do not remember each other. ## What the handoff file contains The format is simple. Four sections: **Current status:** one paragraph summarising where the project is right now. Not a changelog — a snapshot. "The tool installs models, derives hardware-fit settings, and runs 19 golden tasks with hidden tests. 294 tests pass. The web UI exists but a real GPU candidate sweep has not been run yet." **What happened this session:** what the agent accomplished, what it tried and could not finish, and what it learned. Failures go here too. The handoff from the Milkman session that ran ten subagents in parallel and burned the budget in 33 minutes includes the exact failure and the rule that came out of it: cap concurrent subagents at three, ban sub-forking, checkpoint work early. **Next session should:** the goal for the next session, written as a directive. Not a wish list — one goal, or two if they are tightly coupled. **Constraints and risks:** anything the next session must not break, any assumption that turned out false, any edge case that needs a test. The creature-battler's handoff after the refinement audit lists the stat-cap rule, the voluntary-switch bug, and the SQL-shaped string interpolation that needed fixing. The file is typically 200–400 words. Long enough to matter, short enough that the agent reads all of it. ## Why rewrite, not append Appending preserves everything. Rewriting forces a decision: what does the next session actually need to know? The act of rewriting is lossy by design. If a detail does not survive the rewrite, it was not load-bearing. The git log and the risk register are the project's memory; the handoff file is the project's working context. Context does not accumulate. It gets replaced. I have run this on three projects now: the creature-battler (1,725 Godot tests, 7,483 lines of production GDScript), Milkman (294 tests, 485 files, 40,155 insertions across two days), and LEGION itself (64 capability packages). Every one of them survived multiple sessions, across days or weeks, without the agent forgetting what it was doing or why. ## What another builder can do with this If you are working with Claude Code, ChatGPT or any agent harness on a project that will not finish in one session, you need a handoff file. Call it whatever you want. Put it in the root of the repo. Make the agent rewrite it at the end of every session, and make the next session read it first. The format above is what works for me. Yours might be different. The principle is the same: the agent must write down what the next session needs to know, and the next session must read it. The stand-up and wind-down are optional in the sense that you can skip them. They are not optional in the sense that your project will stay coherent if you do. Agents do not remember. You have to build the structure that makes memory unnecessary. The handoff file is that structure.