Write the AI a State-of-Play Before You Close the Tab: A Handoff Note That Resumes the Next Session

An AI coding session dies the moment the tab closes — the same tool tomorrow, a different tool on Tuesday, a fresh browser on a new machine, all start blank. A plain-text handoff note you keep at a path you own, updated at the end of every session, is the cheapest thing to paste at the top of the next one.

This is the human-authored companion to a discipline you may already know from the other direction. Recover your work from the AI tool's session files is about the JSONL your tool already wrote to disk after a session ran; this post is about the state-of-play you pre-write before the next session starts. Both are files you own. Together they close the loop on owning the record of your AI project.

Ishaan Sehgal, writing on Daily Context on 2026-06-30, put the durable half of the claim in one sentence: "When the log is constructed correctly, an agent can be resumed from it alone."¹ He is arguing for a machine-emitted log; the same shape works for a human-authored one. The rest of this tutorial is how to write it, where to keep it, and what to put in it — with sources verified against vendor primaries on 2026-07-04.

The one idea — a state-of-play file is what survives the session

A conversation with an AI is a stream. The moment the process ends, the stream ends with it. A plain-text handoff note is a state-of-play file — a short Markdown file at a path you choose, recording what the project is, where the work is now, what has been tried, and what the next session needs to know.

Sehgal's argument is that the log is the durable artifact and the model is a stateless reader of it: "They're just interpreters and appenders. They read the durable state, act on it, and write the next event back."¹ Marco Somma, writing on the same platform one day earlier, framed the same idea from the model's side: "Memory helps when the answer depends on contingent information absent from the model weights."² The model already has the average; what it needs from you is the situation.

A handoff note is the situation, written down. It is not a substitute for the tool's own transcript — that is what #125 covers — and it is not a substitute for the model's context-window compaction, which every vendor now ships. It is the small, portable, human-shaped file that survives when any of those move underneath you.

Every major CLI ships a session primitive — and you still want your own file

The reason a hand-authored handoff pays off is not that vendors ignore session continuity — they ship it. Anthropic's Claude Code, OpenAI's Codex CLI, and Aider all document their own primitives, and none of them are portable across each other. Your file is.

Anthropic documents /compact plainly in the Claude Code commands reference: it "free[s] up context by summarizing the conversation so far. Optionally pass focus instructions for the summary."³ Next to it sits /resume [session], which "resume[s] a conversation by ID or name, or open[s] the session picker. As of v2.1.144, background sessions appear in the picker marked with bg. Alias: /continue."⁴ Two commands, one purpose — keep going where you left off, inside Claude Code.

OpenAI's Codex CLI ships an equivalent knob. Its configuration reference exposes a history.persistence setting — save-all | none — that "Control[s] whether Codex saves session transcripts to history.jsonl."⁵ Aider's options doc adds a third: --chat-history-file (default .aider.chat.history.md) and --restore-chat-history (default False), plus the environment variables AIDER_CHAT_HISTORY_FILE and AIDER_RESTORE_CHAT_HISTORY for scripted setups.⁶ Three independent CLIs — three vendor-shipped session primitives — all documented, all specific to their own runtime.

That proliferation is evidence, not competition. Every one of these vendors decided the problem was real enough to ship a primitive for. The vendor-neutral answer — the one that keeps working when you switch from Claude Code to Codex, or add ChatGPT for research and Cursor for editing — is a plain file you keep at a path you own. /resume does not follow you across vendors. ~/notes/ai/project-state.md does.

The handoff note — what to put in it

The note is short — aim for one screen. Its job is to prime the next session, not to explain the project from scratch (the code, the tests, and your other notes are still the truth). What follows is a template you can copy verbatim into ~/notes/ai/<project>-state.md and start editing today.

# <project> — state of play

_Last updated: <YYYY-MM-DD HH:MM> · Session #<n>_

## What this project is
<one paragraph. what it does, who it's for, the current scope.>

## Where we are right now
<one paragraph. what's working, what isn't, the current branch/PR/file.>

## What was tried this session
- <thing 1> — worked / failed / rolled back
- <thing 2> — worked / failed / rolled back
- <thing 3> — worked / failed / rolled back

## What was NOT tried (and why)
- <alternative 1> — reason it was ruled out or deferred
- <alternative 2> — reason it was ruled out or deferred

## Open questions (for the next session to answer)
1. <the one decision that would unblock the most work>
2. <the assumption we haven't validated>
3. <the thing we said we'd verify last time>

## Next concrete step
<one sentence. the exact next command / test / commit.>

## Files that matter
- `path/to/thing.ts` — <what it is>
- `path/to/other.md` — <what it is>

## Do NOT do
<the destructive action or dead-end we don't want the next session to try.>

The value is in the constraints, not the sections. Every heading answers a specific question the next session will otherwise re-ask — which is why the sections read as imperatives ("what was tried", "do NOT do") rather than free-form prose. The Do NOT do section is the highest-leverage line — it stops the next session from re-litigating a dead-end you already burned an hour on.

Anthropic's own applied research points at why a short, hand-shaped prefix has an outsized effect. Their September 2024 write-up on Contextual Retrieval reports that prepending a 50–100-token human-shaped context to each chunk before embedding "can reduce the number of failed retrievals by 49%, and when combined with reranking, by 67%."⁷ Their numbers are about retrieval, not chat resumption; the underlying pattern — a small, deliberate, human-shaped context lifts a stateless system's accuracy on the specific job — is the same one your handoff note leans on.

The ritual — update it at the end, paste it at the start

The discipline is two moves and a filesystem convention. At the end of every working session — before you close the terminal or the tab — spend two minutes updating the note. Fill "What was tried this session", update "Where we are right now", write one sentence into "Next concrete step". This is the whole cost.

If you skip the end-of-session update, the note goes stale — and a stale handoff is worse than none, because it lies confidently. Two minutes of writing at the close of a session is the entire premium the discipline charges. Everything else is free.

At the start of every working session, open the note first. Paste it, verbatim, as the first message of the new AI session — before the prompt for what you actually want done. Something like:

Here's where we are on this project. Read it, then help me with the next step.

<paste the whole note>

Now: <the actual ask for this session>.

That two-move ritual is the discipline. The note lives at a path you chose — ~/notes/ai/<project>-state.md is a good default; a folder in your vault next to your other project notes is another — so it does not depend on any vendor account, memory feature, or subscription being live. When the machine changes, the file comes with the directory. When the tool changes, the paste works the same way.

Simon Willison, writing about the session transcripts Claude Code writes to disk, describes what makes these files worth the trouble: "Those transcripts capture extremely important context about my projects: what I asked for, what Claude suggested, decisions I made, and Claude's own justification for the decisions it made while implementing a feature. … they provide an invaluable record of the decisions that went into building features."⁸ His subject is the tool's transcript; the same argument applies to your hand-authored version. The handoff note is the decisions record, condensed by the only person who can condense it honestly.

What the handoff PRIMES — and what it does not GUARANTEE

The handoff note primes the next session — it does not guarantee continuity. Two honest limits and one privacy caveat sit between the discipline and any claim of session-perfect resumability, and they matter enough to name before you rely on this in a production project or paste the file into a tool you did not write.

• It's a prime, not a truth. The next session may still misread the note, hallucinate a step that isn't there, or contradict something you wrote. The source of truth is your code, your tests, your commits — the "state of play" file is a jump-start. Cross-link: The Summary Is a View, the Note Is the Source.
• It goes stale unless you update it. A note last touched two weeks ago will confidently describe a project that has moved. The end-of-session ritual is the whole reason the note is worth writing. Skip the ritual for a week and the file becomes a hazard. If you can't commit to the ritual, use /compact and /resume inside the same tool instead and let the vendor primitives take the load.
• A local file is not an exfiltrated file — the moment you paste it, it is. The handoff note is a plain file on your device until you paste it into an AI session. At that moment, the provider processes the pasted text under whatever training and retention policy is active on your account. Do not put secrets in the handoff note. Cross-link: Secrets do not belong in notes an AI reads.

The OWASP GenAI Security Project frames the logging half of this discipline as a mitigation for a specific class of AI risk. Their LLM06:2025 Excessive Agency entry recommends: "Log and monitor the activity of LLM extensions and downstream systems to identify where undesirable actions are taking place, and respond accordingly."⁹ The vendor's transcript log covers that on the tool's side; your handoff note covers it on the human's side — a receipt of what you decided across sessions, in a folder you can grep.

Common mistakes

Five things that turn a handoff note from an asset into a liability, easier to avoid than fix. The pattern across every one is the same — treating the handoff as more permanent, more private, or more complete than it is, then finding out at the point a fresh session has already re-litigated a decision you meant to preserve.

1. Treating it as a project spec. A handoff note is a state file, not a design doc. If it grows past one screen, cut it. The AGENTS.md you check into the repo is where durable rules for the agent live (see AGENTS.md is the README for your agent); the handoff is the transient, per-session working state.
2. Skipping the end-of-session update. A stale handoff lies. If you can only commit to one of the two moves in the ritual, keep the update — a note without the paste-at-start step still helps the next you; the reverse decays into fiction.
3. Copy-pasting the whole prior transcript into it. The handoff is condensed by hand, on purpose. If you want the full transcript, back up the vendor's own session file per #125. The handoff is the summary only you can write.
4. Putting secrets in the note. The moment you paste the note into an AI session, its contents leave your device. Keep API keys, credentials, and PII out of the file. Cross-link: Secrets do not belong in notes an AI reads.
5. Confusing it with the vendor's memory feature. ChatGPT and Claude both offer persistent "memory" that survives across chats. The handoff note is the vendor-independent version of the same idea — it works on a new machine, a new account, a new tool, or an incognito window. If you use the vendor memory too, copy it out into a file you own on a regular cadence: Copy your AI memory into a file you own.

Frequently asked

Seven questions readers ask about handing an AI project off across sessions. The first six draw from vendor docs, ecosystem tools, and the two 2026-06 essays that reargued the case; the last is a straight portability question. Each answer points back into the section above — a skimmer can jump straight to the file layout and skip the argument.

How do I keep an AI conversation going after the session ends or when I switch tools — without relying on the vendor's memory feature? Keep a plain-Markdown handoff note at a path you own, update it at the end of every session, and paste it at the top of the next one. Every major CLI ships a session primitive (/compact, /resume, --restore-chat-history), but none of them cross vendors. The file does.

How do I resume a Claude Code session? Inside Claude Code, use /resume [session] — it opens the session picker, and as of v2.1.144 background sessions appear marked with bg; the alias is /continue.⁴ To resume across Claude Code and any other tool, keep a handoff note at a path you choose and paste it into the new session.

How do I switch from ChatGPT to Claude and keep my project context? The vendor answer is that you can't — memory and history live in each vendor's account. The vendor-neutral answer is a plain-text handoff note in a folder you own: pasted into a fresh Claude session, it primes the tool the same way it primes a fresh ChatGPT tab.

Where does Claude Code save my session transcripts? ~/.claude/projects/<project>/<session>.jsonl on macOS and Linux; the full tour, including the Windows and CLAUDE_CONFIG_DIR overrides and the equivalent paths for Codex, Cursor, Gemini CLI, Copilot CLI, and Aider, is in #125. Your handoff note is the human-authored complement to that vendor-written transcript.

What is /compact in Claude Code and when do I use it? /compact [instructions] "free[s] up context by summarizing the conversation so far. Optionally pass focus instructions for the summary."³ Use it inside a long-running session that is pushing the context window; use the handoff note between sessions, where /compact no longer helps.

How do I keep AI memory across chats without using ChatGPT memory? Author your own file. A Markdown handoff note at a path you own, updated at the end of every session, works even if you're on a new machine, a new account, or an incognito window — which the vendor memory does not.

Can I resume an Aider chat from a previous session? Yes. Aider's own docs document --chat-history-file (default .aider.chat.history.md) and --restore-chat-history (default False); the environment variables are AIDER_CHAT_HISTORY_FILE and AIDER_RESTORE_CHAT_HISTORY.⁶ The handoff note is the version of the same idea that survives the day you leave the Aider repo for a different tool.

The one-line practice

The whole discipline compresses to one line — keep a plain-Markdown handoff note at a path you own, update it at the end of every session, and paste it at the start of the next one. The file survives when the tool changes. The paste is the resume.

Steph Ango wrote the philosophy in July 2023, before any of the 2026 CLIs shipped: "File over app is a philosophy: if you want to create digital artifacts that last, they must be files you can control, in formats that are easy to retrieve and read. Use tools that give you this freedom. … Apps are ephemeral, but your files have a chance to last."¹⁰ A session is an app; a handoff note is a file. Sehgal and Somma made the argument again this week for AI agents specifically; Ango made it in 2023 for digital work in general. The tools change; the practice does not.

MNMNOTE keeps its own notes as plain Markdown on your own device — the same file-over-app discipline this post recommends for your handoff notes. mnmnote.com