How to hand off an AI coding session

How to hand off an AI coding session comes down to one habit: before a session ends, write a short note that lets the next session continue without reading the transcript. The next session might be the same agent tomorrow, a different agent, or a colleague. None of them can rely on the old conversation, and the agent that did the work is the least reliable witness of what it did. A good handoff records the goal, the current state of the code, what was tried and rejected, the exact commands and results, and the single next step. It lives with the task, not in the chat. And it is tested: the next session should be able to restate the plan from the note alone. The routine below takes five to ten minutes and works with Claude Code, Codex CLI or any other agent. It complements, rather than repeats, the case for durable project memory.

Step 1: Stop at a checkpoint you can name

Do not hand off in the middle of an edit. Before writing anything, bring the working tree to a state you can describe in one sentence.

If the change is coherent, commit it on a branch with a message that says what it does and what it does not do yet, for example 'Add retry to webhook sender; backoff not configurable yet'. If it is not coherent, stash it or commit it as clearly marked work in progress so nobody mistakes it for finished work.

Then record three facts you will put in the note: the branch name, the commit identifier, and whether the tests that matter pass right now. Run them yourself rather than copying the agent's last claim. 'Tests passed' from forty minutes ago, before two more edits, is not a current fact.

If the session left anything running, such as a dev server, a watcher or a background job, stop it or write down that it is running and how to stop it. Interrupted work is much easier to recover when its state was named before the interruption; recovering interrupted agent work covers the harder case where it was not.

Step 2: Write the handoff note

Keep it short enough to read in two minutes. A note that runs to pages will itself be skimmed or truncated. Use the same headings every time so readers know where to look.

Goal: one sentence on the outcome, for example 'Webhook delivery retries failed requests up to 5 times with backoff.'

State: branch, commit, which acceptance criteria are met and which are not.

Evidence: the exact commands run and their results, such as 'pytest tests/test_webhooks.py: 11 passed, 1 failed (test_backoff_cap)'. Paste the failing line, not the whole log.

Decisions and rejected options: what you chose and what you ruled out, with the reason. 'Rejected: a queue library, because the service must stay dependency-free.' This is the part summaries lose first.

Open questions: anything that needs a human decision.

Next step: one concrete action, small enough to start immediately.

Files touched: a list, so the next session can check them first.

You can ask the agent to draft the note, but edit it yourself. The agent's version tends to overstate progress and omit dead ends.

Step 3: Put it where the next session will look

A handoff note in a chat message or a scratch file on the desktop is a note nobody finds. Store it with the unit of work it describes. That might be the issue or ticket, a task file in the repository, or a project card. One record per task works better than one running log for the whole project; per-task Markdown memory explains the structure.

Make the location predictable. If tasks live in a docs/tasks folder, the note goes in the task's file under a dated 'Handoff' heading. If they live in an issue tracker, it goes in a comment on the issue. The next session's first instruction can then be the same every time: read the task record, including the latest handoff, before doing anything else.

If you are switching tools, for example from Claude Code to Codex CLI, the note is the bridge. Neither tool can read the other's conversation. The mechanics of that switch are covered in switching a task between Claude Code and Codex.

Never paste credentials, tokens or private connection strings into the note, even temporarily. Handoffs are copied into prompts and sent to providers; see keeping secrets out of AI project memory.

Step 4: Test the handoff with a cold read

A handoff is only as good as what a reader can do with it. Test it before you rely on it.

Start a new session with no history. Give it only the task record and ask it to restate the goal, the current state and the next step in its own words, and to list anything it finds ambiguous. Do not let it edit files during this check. A read-only or planning mode is the right tool if yours has one, for example plan mode in Claude Code or a read-only sandbox in Codex CLI.

Compare its answer with what you meant. If it misses a rejected option or proposes the approach you already ruled out, the note is missing that fact. Fix the note, not the prompt.

Next, have the new session check that the repository matches the note: the branch and commit exist, the listed files are the ones changed, and the test result is still what the note says. If anything differs, the note is already stale project memory and the first job is to reconcile it.

The same test works for handing work to a person. If a colleague can start from the note without asking you a question, it is a good handoff.

QUESTIONS

What should a handoff note for an AI coding session include?

The goal in one sentence, the branch and commit, which acceptance criteria are met, the exact commands run with their results, decisions and rejected options with reasons, open questions and one concrete next step. A list of touched files helps the next session check its starting point quickly.

Can the AI agent write its own handoff note?

It can draft one, and that saves time, but review it before saving. Agents tend to describe progress more favorably than the evidence supports and to leave out failed attempts. Run the key checks yourself and add any rejected options the draft forgot.

How long should a handoff note be?

Short enough to read in about two minutes, usually under a page. Link to logs and diffs instead of pasting them. If the note grows long, the task is probably too large and should be split into smaller pieces with their own records.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk
• How to find and organize work across projects

RELATED HARNESS PAGES

• Per-task Markdown memory Per-task Markdown memory: one short record per unit of work, with outcome, scope, criteria, findings and next step, instead of one global notes file.
• Switching a task between Claude Code and Codex Switching a task between Claude Code and Codex mid-way: what carries over, what stays behind in the old session, and a handoff checklist.
• Stale AI project memory Stale AI project memory: how notes and evidence an agent reads fall out of date, how to detect it, and what a freshness check cannot tell you.
• Recovering interrupted AI agent work Recovering interrupted AI agent work: inspect what was written, check what is still running, refuse blind replays and resume with a fresh authorization.
• Keeping long-running AI coding projects on track Keeping long-running AI coding projects on track: written goals, scheduled re-planning, drift checks between plan and code, and tested backups.
• Keeping secrets out of AI project memory Keeping secrets out of AI project memory: what never goes into notes, cards, prompts or handoffs, and redaction habits that hold up.