Claude Code session handoff: keep the next session moving

Resume the conversation, or hand over the work?

If you only need to continue the same conversation, try Claude Code’s built-in session resumption first. A separate handoff is useful when you want a fresh session, another agent, or a concise record outside the transcript.

Claude Code also has persistent instructions and auto memory. A handoff serves a narrower purpose: stating where this particular piece of work stopped, with enough evidence to continue.

See Claude’s workflow documentation and memory documentation for the built-in options.

Leave a small, checkable record.

A good handoff answers: what are we trying to do, what changed, why, what was checked, and what happens next? “Almost done” tells the next session very little.

# Ledgerly handoff — Fernhill Labs (fictional example)

Goal: show useful card errors without losing the form input.
Current work: feature/card-errors; changes are local, not merged.
Changed: the error message now appears below the card field.
Checked: the focused validation test passes on this branch.
Not checked: the payment-provider sandbox and mobile layout.
Decision: keep the entered values after a failed attempt so the
customer can correct the card without filling in the form again.
Open question: which errors should offer another payment method?
Next step: test a declined card in the sandbox, then check mobile.
Before editing: inspect the diff and confirm this note still matches.

Use your actual branch and file paths, and link the relevant issue or pull request when one exists. Keep credentials and customer data out of the note. Replace the current summary as work progresses; keep durable decisions in a separate record if you need their history.

At the end of the session

Ask the agent to write the handoff while it still has the context:

Write a concise HANDOFF.md for the next session. Include the goal,
branch, current changes, decisions and reasons, checks actually run,
unverified behavior, open questions and the next step. Check the diff
before writing. Do not call untested or unmerged work finished.

HANDOFF.md is a file convention you choose, not a special Claude Code feature. Keep repository rules in CLAUDE.md; keep the current task’s changing state in the handoff.

Read it, then check what changed.

Explicitly ask the next session to read the note. Do not assume that a file named HANDOFF.md loads automatically.

Read CLAUDE.md and HANDOFF.md. Compare the handoff with the current
branch, diff and relevant test results. Tell me what is still true,
what changed and the next step. Flag missing evidence before editing.

For the example above, the next useful action is the sandbox check. If someone has already merged or changed the branch, update the handoff before continuing.

• Keep claims precise. A passing unit test does not establish that the payment flow works.
• Keep decisions with reasons. “Preserve form input” is easier to maintain when the next agent knows why.
• Make the next step executable. Name the check or change, and any answer it depends on.

When a handoff file becomes more work.

A file can be enough for one project and a straightforward sequence of sessions. Shared project memory becomes useful when work spans several repos, agents need the same decisions, or you keep reconciling notes with issue status.

In Verdical, connected agents explicitly record work and decisions as they go. A new session can retrieve the project state, the next step and what is waiting on you. Decisions keep their reasons; linked GitHub activity updates work status.

Verdical does not extract everything from a conversation. Agents must use the connected tools to read and record the work. A merged pull request is evidence of a merge, not a guarantee that the feature behaves correctly in production.

Read how Verdical and CLAUDE.md fit together, or see how Verdical works. Access is by invitation during the private beta; repository linking is assisted.