‹ Guides

Guide · Claude Code

Claude Code session handoff: start the next session where this one stopped

Claude Code is at its best deep in a task, and that depth is exactly what you lose when the session ends, when you run /clear, or when a long session compacts. Here is what Claude Code already keeps, what it doesn't, and a handoff routine that carries the work into the next session.

What Claude Code keeps, and what it doesn't

• CLAUDE.md is loaded at the start of every session. It is the right place for rules and conventions. It is the wrong place for state: nobody rewrites it at every pause.
• claude --continue and claude --resume reopen an earlier conversation on the same machine. That brings the whole transcript back, dead ends included, and it doesn't help a fresh session, another machine, a cloud session or another model.
• Compaction (/compact, or automatic when the context fills) replaces the history with a summary. It keeps the session going, and the summary is lossy: the reasons behind decisions are the first thing to go.

What's missing is a short, deliberate record of where the work stands, written at a natural pause and read at the start of the next session.

A handoff you can start using today

Add a file such as HANDOFF.md and two lines to CLAUDE.md:

## Session routine
- At the start of a session, read HANDOFF.md before doing anything else.
- Before you stop, or before /clear, rewrite HANDOFF.md: tried, decided (and why), done,
  failed (with the error), state (working / blocked / open), next step, where the detail is.

Keep it short: a few hundred words. The point is the state and the reasons, not a diary.

Where the file approach breaks

• Several lines of work in one repo end up fighting over one file.
• It stays on one machine and one branch, so a cloud session or a teammate starts from an old copy.
• Codex, Cursor or Gemini CLI need their own instructions to read it, and nothing checks the note is current.

Make it automatic, on any machine and any model

With ResumeState the handoff lives in your account, under a lane for each line of work. You paste two lines into Claude Code once; it connects itself with a one-time code, downloads a small helper (Python standard library only, checked against a published SHA-256), and adds a start-and-end routine to its own instructions. The routine comes down to two commands:

# at the start of a session
python3 ~/.resumestate/rs.py resume <lane code>

# at the end of a session (the handoff goes in on standard input)
python3 ~/.resumestate/rs.py handoff <lane code>

The helper keeps its pass in a file only your user can read and renews it by itself; it never prints a token. Because the handoff lives in your account rather than in the repo, the next session can be Claude Code on another machine, a cloud session, or Codex, Cursor or Gemini CLI connected to the same account. Each one resumes the same lane.

What a good Claude Code handoff looks like

state: blocked
tried:   ran the migration against a copy of production; 2 tables failed the charset check
decided: convert tables before re-adding foreign keys (MariaDB refuses the other order)
done:    migration 012 written; 41 tests pass
failed:  "1833: Cannot change column used in a foreign key constraint" on accounts.id
next:    drop and re-add the two keys around the conversion, then rerun the copy
detail:  db/migrations/012_charset.sql, branch charset-fix

Questions

Related guides

• Why your AI forgets everything between sessions: Each new chat starts empty, and what to save so the next session starts where you stopped.
• Hand a session to a cheaper or different model: Let the strong model reason, let a cheaper one do the volume, and keep the thread between them.
• An MCP server for session continuity: What an MCP memory or continuity server should do for coding agents, and how ResumeState connects.