The Claude Code Handover: End Every Session With a File the Next One Can Act On

I built a product with Claude Code and Codex taking turns on the same repository. One of the mistakes from that build had nothing to do with code. A planning document described what the app should do, and later sessions read it and assumed those features existed.

A Claude Code handover prevents that class of mistake. It's a short entry in a file, written at the end of every session, that says what actually changed, what was verified, what's still running and what to do next. The next session reads it before touching anything, and starts from the truth instead of from a guess.

Why does Claude Code need a handover at all?

Because the conversation is the only memory a session has, and it doesn't last. Anthropic's documentation puts it plainly: each Claude Code session begins with a fresh context window.¹ Within a session, the context fills up as Claude reads files and runs commands, and Anthropic's own best-practices guide warns that performance degrades as it fills.² The recommended fix is to run /clear between unrelated tasks, which also wipes everything you didn't write down.

Three situations make the gap expensive:

• You clear or compact a long session. A summary keeps the gist and drops details like which test failed and why.
• You switch tools. Claude Code and Codex can't read each other's chats or memory. Git and files are the only shared state.
• Someone else picks up the work. A colleague, a client, or you in two weeks. None of them were in the chat.

CLAUDE.md doesn't solve this. It's meant for things that are always true about the project: commands, conventions, architecture. Anthropic recommends keeping it under 200 lines,¹ and a log of what happened on Tuesday doesn't belong there. A handover file is the changing half: what happened, what's verified, and what's next.

What goes into a Claude Code handover?

Here's the entry template from the free coding-agent-handover skill. It's short on purpose: an entry should be readable in under two minutes.

## 2026-10-16 18:40 · <one-line summary>

**For <owner>:** <plain words: what changed in the product, what needs to be
running, and what to try first>

- **Goal:** …
- **Shipped:** … · **Not shipped:** …
- **Files touched:** `path` (why), …
- **Checks run:** `npm run build` → passed · `npm test` → 2 failed (see risks)
- **Manually tested:** <flows, screen widths>. **Not tested:** <…>
- **Decisions:** <owner>, 16 Oct: … (one line each, dated and attributed)
- **Rollback point:** `abc1234` on `<branch>`
- **Still running:** dev server on :3000 / nothing
- **Risks and unknowns:** …
- **Next step:** <the first action for the next session>
- **Do not do next:** <tempting work that is out of scope>

### Ready-to-paste prompt for the next chat
> Repo: <path>, branch <name>. Read <agent guide> and the newest entry in
> <handover file> first. Task: <one sentence>. Constraints: <…>.
> Before you finish: run <commands>, then add a new handover entry.

Each line exists because leaving it out caused a problem at some point:

What rules make a handover trustworthy?

A template helps, but the rules behind it are what make the next session trust the file. These came from real failures:

• Write the current state, not the intent. Mark anything unbuilt as "planned". The handover is the truth about what shipped.
• Evidence, not adjectives. "Works" means nothing. "npm test → 48 passed" is a fact the next session can rely on.
• Decisions live in the file. A decision that exists only in a chat or in one tool's memory is lost at the next switch. Date it and say who made it.
• Save first, then summarize. Before writing the handover, move results, generated text and test output out of the chat into files. A crash deletes whatever lives only in the conversation.
• Commit, or list. Either commit the work or name every uncommitted file in the entry. Never end a session with silent changes.
• No secrets. No keys, tokens or .env values in a handover. Point to .env.example instead.

Where should the handover file live?

In the repository, next to the code, so it travels with every clone and every branch:

• Use the project's existing file if there is one: docs/handover.md, HANDOVER.md, or a progress.md and next_sprint.md pair.
• If there's none, create docs/handover.md and add one line to the agent guide that points to it.
• Newest entry first. Don't rewrite old entries; mark superseded ones as superseded.

The pointer matters because Claude Code reads CLAUDE.md automatically at the start of every session,¹ and Codex reads AGENTS.md. One line in each ("Read the newest entry in docs/handover.md before starting") means every session, in either tool, starts by reading the same file. If you use both tools, the setup is in how to use Claude Code and Codex together.

Handover, /compact or --continue: which one when?

Claude Code has built-in ways to keep context, and they're useful. They just solve a different problem than a handover:

You can tell Claude Code what to keep during compaction by adding an instruction to CLAUDE.md, for example to always preserve the list of modified files and test commands.² That helps within a session. The handover is what survives beyond it.

The ready-to-paste prompt

The last part of every entry is the one people skip, and the one that saves the most time. Instead of explaining the project again in a new chat, you paste three lines:

Repo: ~/code/shop, branch feature/rate-limit. Read CLAUDE.md and the newest
entry in docs/handover.md first. Task: raise the site-wide daily cap and add a
test for it. Constraints: don't touch src/data/; no new dependencies; no push
without my OK. Before you finish: run npm test, then add a handover entry.

It works because it names the repository and branch (so the session doesn't wander into the wrong one), points to the files that hold the context, states one task, and fences what must not change. Pair it with a two-minute preflight at the start of the next session; the session-start checklist covers that half.

Make Claude write it every time

You can ask for a handover in plain words at the end of each session, or install it as a skill so the format and the rules are the same every time. The free starter kit's coding-agent-handover skill does exactly that, and switches on when you say "write the handover", "wrap up" or "update progress.md". Its companion coding-agent-session-start runs the preflight at the beginning. They work in Claude Code, Codex and other agents that read SKILL.md files.

FAQ

What's the difference between a handover and CLAUDE.md?

CLAUDE.md holds what's always true about the project, and Claude Code loads it every session, so it should stay short. The handover holds what happened and what's next, and changes every session. Link the two: one line in CLAUDE.md points to the handover file.

Should the handover file be committed to git?

Yes, if the repository is private. It's how the next session on another machine, branch or tool gets the context. Keep secrets out of it, and if the repository is public, keep the file somewhere private and point to it.

How long should a handover entry be?

Readable in under two minutes. Link to logs, reports and long outputs instead of pasting them.

Does this work with Codex and Cursor?

Yes. The handover is a plain Markdown file in the repository, so any agent can read it. The only setup is making each tool's guide (CLAUDE.md for Claude Code, AGENTS.md for Codex) point to the same file.

Can Claude write the handover automatically?

It can write it whenever you ask, and a skill makes the format consistent. Claude Code also supports hooks that run at fixed points in a session,² if you want a reminder to fire every time.