Claude Code Session Handoff: How to Resume Work Without Re-Explaining Everything

Tuesday, 4:50 pm. I'm forty minutes into moving our payment retry logic out of the request handler and into the client, Claude Code has the whole shape of it in its head, and a calendar reminder pops up. I close the terminal. Wednesday morning I open it again, type "continue the retry refactor," and get a polite question back: which retry refactor? Everything we'd worked out the day before was gone.

If you searched for "claude code session handoff how to resume work," you've had that morning too. The good news is that Claude Code has a real answer for the simple case. The bad news is that the simple case is smaller than it looks.

What Claude Code Gives You Out of the Box

Claude Code keeps your sessions on disk. Two flags bring one back:

claude --continue      # reopen the most recent session in this directory
claude --resume        # pick from a list of past sessions

That restores the conversation: what you asked, what it answered, which files it touched. For the Tuesday-to-Wednesday case on the same laptop, in the same repo, this is usually all you need. Start here before you build anything.

Where --resume Stops Working

I leaned on --resume for months and kept hitting the same four walls.

• A different machine. Sessions live in your local home directory. Your desktop doesn't know what your laptop did.

• A different tool. Open the same repo in Cursor or Claude Desktop and there is nothing to resume. Each tool has its own history.

• A compacted or full context. Long sessions get summarized to make room. The summary keeps the gist and drops the details, and the details are usually the decisions.

• Weeks later. Resuming a three-week-old session drags in a lot of stale conversation to find the one decision that still matters.

In every case the thing you actually want back is not the transcript. It's the handful of decisions and facts the transcript contained.

The Manual Handoff, and Why It Rots

The workaround most of us reach for is a handoff note: a HANDOFF.md, a section in CLAUDE.md, or a paragraph you paste at the start of every session. It works, and I still recommend a short one for anything you'd tell a new teammate on day one.

It stops working the moment it stops being short. Decisions pile up, half of them go stale as the code moves, and the agent starts trusting a note that is no longer true. I wrote about that failure mode in Why Your CLAUDE.md Goes Stale. A hand-maintained file is a snapshot. A real project makes decisions faster than anyone updates a snapshot.

Persistent Memory: Saving the Decisions, Not the Transcript

The approach that finally stuck for me was to stop trying to preserve the conversation and start preserving what came out of it. During the session, the agent saves the things that matter: "retry logic goes in the client, not the handler," "we dropped the caching layer," "the vendor API rejects batches over 50." In the next session, in any tool, on any machine, it searches that memory before it starts and picks up from the decisions instead of from zero.

This is what I built ContextForge for. It runs as an MCP server, so the same memory is reachable from Claude Code, Claude Desktop, Cursor, Windsurf and ChatGPT. One line per tool:

claude mcp add contextforge -e CONTEXTFORGE_API_KEY=<your-key> -- npx -y contextforge-mcp

Two things worth being clear about, because the marketing version of this idea tends to skip them. First, nothing is injected magically. The agent has memory tools the same way it has a tool to read a file, and it saves and recalls because your CLAUDE.md tells it to. Second, memory belongs to the Project linked to your repo, so a decision saved from Claude Code on the desktop is there when Cursor opens the repo on the laptop. That is the whole point.

A Handoff That Actually Survives

Here is the loop I use now for the retry refactor, or anything longer than one sitting.

1. Before you close the terminal, ask the agent to save where things stand: what's done, what's next, and any decision you'd hate to re-derive. Thirty seconds.

2. Next session, same machine, run claude --continue. You get the transcript back, and the saved decisions are in memory as a safety net for anything compaction dropped.

3. Next session, different machine or tool, just start. The agent queries memory for the project, finds "retry refactor: client-side, handler untouched, next step is the timeout config," and continues from there.

4. When the code changes under a memory, ContextForge flags it as possibly stale. You or the agent confirm it, correct it, or forget it. Skip this and old decisions quietly steer new work.

If you split your day across several tools, How to Share Context Between Claude Code and Cursor walks through step three in more detail. For the three-command setup with a video, see Give Your AI Coding Agent a Memory That Survives Every Session.

Where It Falls Short

• Setup is real. An API key and an MCP entry per tool. Ten minutes, once, but not zero.

• Memory only holds what gets saved. If nobody saves the decision, it isn't there. The pre-close habit in step one is doing most of the work.

• It doesn't replace reading the code. Memory says what you decided. The file says what the code does today. The agent needs both.

• It's early. Small team, active development, rough edges. Core first, polish second.

A Practical Next Step

Tonight, before you close Claude Code, type one line: "save where we are on this task and what's next." Tomorrow, open the same repo in a different tool or on a different machine and ask it what you were doing. If it answers correctly, you have a session handoff that doesn't depend on a transcript. If you want the setup walkthrough first, start with MCP Memory Server: How to Give Claude & Cursor Persistent Memory.