# Claude Code Handoff: Passing Work Between Sessions, Codex and Cursor Without Losing Context

Source: https://lotsnotes.com/blog/claude-code-handoff
Published: 2026-10-23T00:30:29.102394+00:00

To hand off work from Claude Code, end each block by writing a handoff note (what's done, what's in progress, the next three steps, the decisions) somewhere every agent can read, and start the next session by reading it. `claude --resume` brings back a conversation on the same machine, but Codex and Cursor never see Claude Code's transcripts or auto memory. A shared note does.

I run LotsTech's agents this way: a different agent may pick up tomorrow's work, sometimes Claude Code, sometimes Codex, sometimes a cloud agent, and the rule is that everything needed to continue lives in notes, never only in a chat or on one computer. Below is what Claude Code, Codex and Cursor each carry over between sessions today, from their own docs checked on 22 October 2026, and the handoff note pattern I use with LotsNotes over MCP.

## What carries over, and what doesn't

Checked on 22 October 2026 in the Claude Code docs, the Codex docs and the Cursor docs.

| | Claude Code | Codex CLI | Cursor |
|---|---|---|---|
| **Resume a past session** | `claude --continue` (latest in this directory) or `claude --resume <name or ID>` | `codex resume` (`--last` for the latest in this directory) | `@Chats` brings context from a previous Cursor conversation into a new one |
| **Where sessions live** | JSONL transcripts in `~/.claude/projects/<project>/`, kept 30 days by default | Saved sessions on your machine, listed by `codex resume` | Chats in Cursor; Agent checkpoints are stored locally |
| **Branch a session** | `/branch` or `--fork-session` | `codex fork` or `/fork` | Side chats (`/side`) |
| **When context fills** | Auto-compaction; `/compact [focus]` by hand | `/compact` | Older turns are compressed into a summary |
| **Instruction file** | `CLAUDE.md`, or `AGENTS.md` when there's no `CLAUDE.md` | `AGENTS.md` (global, then root down to your folder) | `.cursor/rules/*.mdc` and `AGENTS.md` (root and nested) |
| **Its own memory** | Auto memory, machine-local | Local memory store | Rules; no memory between completions without them |
| **Import from another agent** | `/import codex`, `gemini` or `cursor`: instruction files, MCP servers, commands, subagents, skills | `/import` from Claude Code or Cursor: setup, project files, up to 50 chats from the last 30 days | Migration guides for VS Code and JetBrains; none for Claude Code or Codex in its docs index |
| **Reads the other tools' sessions live** | No | No | No |

The last row is why handoffs break. Each tool is good at continuing its own work on the machine where it ran. None of them reads what the other two are doing right now.

## Passing work between Claude Code sessions

Inside Claude Code, the conversation itself is the handoff, as long as you stay on one machine.

- **Name sessions you'll come back to.** `claude -n "billing-refactor"` names a session at start, and `/rename` names it later. Then `claude --resume billing-refactor` opens it directly, and the `/resume` picker shows the name.
- **`claude --continue`** opens the most recent session in the current directory.
- **Branch before a risky turn.** `/branch try-other-approach` copies the conversation so far and switches you into the copy, leaving the original intact. From the shell, `claude --continue --fork-session` does the same.
- **Compact with a focus.** `/compact keep the migration plan and failing tests` summarizes the conversation with your focus instructions, so the parts the next turn needs survive.
- **Export for a person.** `/export handoff.txt` writes the conversation as readable text.
- **PR-linked sessions.** When Claude Code opens a pull request, `claude --from-pr 123` finds the sessions linked to it.

Two limits make this a same-machine handoff. Transcripts are stored locally and cleaned up after 30 days by default (`cleanupPeriodDays` changes that). And Anthropic's memory docs say auto memory is machine-local: it isn't shared across machines or cloud environments. One more detail from the sessions page: a resumed session doesn't restore flags such as `--mcp-config`, `--settings` or `--add-dir`, so pass them again.

`claude --teleport` resumes a Claude Code cloud session in your local terminal, which covers the cloud-to-laptop case inside Claude Code. It doesn't help Codex or Cursor.

## Claude Code to Codex

Codex reads `AGENTS.md` before it does any work: `~/.codex/AGENTS.md` first, then each directory from the project root down to where you started, with closer files winning, up to 32 KiB by default. Claude Code reads `AGENTS.md` too when there's no `CLAUDE.md` (Claude Code v2.1.277 or later), or through an `@AGENTS.md` import inside `CLAUDE.md`. So one committed `AGENTS.md` gives both tools the same rules.

For moving the work itself, Codex has `/import`. From a local Codex CLI session, choose Claude Code, then select the setup, project files and recent chats to bring over. OpenAI's import page lists what maps where: instruction files to `AGENTS.md`, Claude Code project memories to Codex memories, MCP server configuration, hooks, slash commands (as skills), subagents, and chats from the last 30 days, up to 50 in the CLI. Importing leaves your Claude Code setup unchanged.

That's a migration, not a handoff. It copies what existed at that moment, from that machine, one way. If you go back to Claude Code tomorrow, nothing Codex learned comes with you. OpenAI's own memories page says the same about memory: keep required guidance in `AGENTS.md` or checked-in docs, and treat memories as a helpful recall layer, not as the only source for rules.

## Claude Code to Cursor

Cursor reads `AGENTS.md` in the project root and in subdirectories, alongside its own `.cursor/rules` files (which must be `.mdc` files with frontmatter; plain `.md` files there are ignored). Cursor's rules page puts it plainly: models don't retain memory between completions, and rules provide the persistent context.

Conversation history stays inside each tool. In Cursor, `@Chats` references a previous Cursor conversation, not a Claude Code one. Going the other way, Claude Code's `/import cursor` brings Cursor's instruction files, MCP servers, commands, subagents and skills into Claude Code, not its chats.

Cloud agents add one more gap. Cursor's cloud agents run in their own VMs and, per Cursor's docs, can't read files from your local home directory. Anything that lives only in `~/.claude` or `~/.cursor` on your laptop isn't there.

## The handoff note pattern

What the next agent needs isn't the whole transcript. It's the current state of the work, in a form any agent can read in a few seconds. I keep one note per agent or project called `handoff`, rewritten at the end of every working block:

```md
# Handoff: billing-refactor

Updated: 2026-10-22 18:40 IST by Claude Code

## State
Branch `billing-refactor`, PR #123 open, CI green except `invoice.test.ts`.

## Done this block
- Moved tax rounding into `lib/tax.ts`; old helper deleted.
- Migration 041 written, not applied.

## In progress
- `invoice.test.ts`: two snapshots fail after the rounding change. Expected, need regenerating.

## Next 3 steps
1. Regenerate the two snapshots and check the totals by hand.
2. Apply migration 041 on staging.
3. Ask the founder before touching the refund flow.

## Decisions
- Round per line, not per invoice (founder, 2026-10-22).

## Don't touch
- `lib/payments/`: owned by another session today.
```

Rules that live for months (stack, conventions, "never touch production") go in `AGENTS.md`. The handoff note changes every block, so it doesn't belong in a committed file.

### Where to keep it so every agent reads it

The note has to be somewhere Claude Code, Codex, Cursor and cloud agents can all reach. I keep it in [LotsNotes](https://lotsnotes.com): a workspace for the business, a folder per project or agent, and in each folder an `AGENTS.md`, a `handoff` and a `ledger` note. Every agent reads the same note over MCP, and the cloud ones over the REST API. It works with the AI agent you already use, and you can read and edit the same note on lotsnotes.com.

Connect each tool once (full steps on [lotsnotes.com/mcp](https://lotsnotes.com/mcp)):

- **Claude Code:** `claude mcp add --transport http lots-notes https://api.lotsnotes.com/mcp`, then `/mcp` and choose Authenticate.
- **Codex:** `codex mcp add lots-notes --url https://api.lotsnotes.com/mcp`, then `codex mcp login lots-notes`.
- **Cursor:** add `"lots-notes": { "url": "https://api.lotsnotes.com/mcp" }` under `mcpServers` in `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project). Cursor opens the sign-in on first connect.

### The tools, start to finish

Every tool below is in the LotsNotes [tool list](https://api.lotsnotes.com/tools.json).

**Start of a session:**

1. `list_workspaces`, then `list_folders` to find the project's folder.
2. `find_context` with `workspace_id` and `folder_id`. Workspace notes come back every time, plus that folder's own notes, each with a one-line summary.
3. `read_note` on `AGENTS.md` first, then `handoff`. `read_note` returns the note's `current_version`; the agent keeps it.

**End of a block:**

4. `save_context_note` on `handoff` with the new body and `expected_version` set to the version it read. If another agent changed the note in the meantime, the save fails with a conflict instead of overwriting it; the agent reads it again and merges.
5. `create_context_note` for a new note, such as a decision record, with a one-line `summary` so the next agent can pick it from search results.

**When a handoff goes wrong:**

6. `list_context_versions` and `restore_context_version` bring back any earlier version of the note. Restoring keeps the current state in history too.

Every note the agent reads or saves comes back with its lotsnotes.com link, so it can hand you the link to check what it wrote.

### The prompts I use

End of a Claude Code session:

> Before we stop: rewrite the `handoff` note in the billing-refactor folder in LotsNotes. Include state, done this block, in progress, next 3 steps, decisions and don't-touch. Save it with the expected_version you read, then give me the link.

Start of the next session, in Codex, Cursor or Claude Code:

> Read AGENTS.md and the handoff note in the billing-refactor folder in LotsNotes, tell me in three lines where things stand, then start on step 1.

To make it automatic, put two lines in the repository's `AGENTS.md`, which Claude Code, Codex and Cursor all read: "At the start of a session, read the handoff note in LotsNotes folder billing-refactor. Before you stop, rewrite it."

## Keep secrets out of the handoff

A handoff note is shared context, so every agent you connect reads it. Never put API keys, tokens or passwords in it. Notes you want next to the work but out of every agent's reach can be private notes in LotsNotes: they stay on lotsnotes.com and are never returned over MCP or the API. More on that in [Is LotsNotes Safe?](https://lotsnotes.com/blog/is-lotsnotes-safe).

If you're still deciding where each kind of instruction belongs, I compared them in [AGENTS.md vs CLAUDE.md](https://lotsnotes.com/blog/agents-md-vs-claude-md) and [Claude Skills vs Projects vs MCP vs CLAUDE.md](https://lotsnotes.com/blog/claude-skills-vs-projects-vs-mcp-vs-claude-md).

LotsNotes is free for one person (1 workspace, 3 folders, unlimited notes, MCP and REST), and [Pro](https://lotsnotes.com/pricing) is $99 once for unlimited workspaces, folders and teammates.

## FAQ

### How do I continue a Claude Code session later?

Run `claude --continue` in the same directory for the most recent session, or `claude --resume <name>` for a named one. Name a session with `claude -n` or `/rename`. Transcripts are stored on your machine in `~/.claude/projects/` and kept for 30 days by default.

### Can Codex continue a Claude Code session?

Not live. Codex's `/import` copies Claude Code setup, project files, project memories and up to 50 chats from the last 30 days into Codex, once, on that machine. To keep working back and forth, both should read the same `AGENTS.md` and the same handoff note.

### Does Cursor read CLAUDE.md or Claude Code's memory?

Cursor's rules docs cover `.cursor/rules`, User Rules, Team Rules and `AGENTS.md`, not `CLAUDE.md`. Claude Code's auto memory is machine-local in `~/.claude/projects/<project>/memory/`. Put shared rules in `AGENTS.md`, which both read.

### What should a handoff note include?

The current state (branch, PR, what passes and fails), what was done this block, what's in progress, the next three steps, decisions with who made them, and anything the next agent must not touch. Keep it short enough to read at the start of every session.

### Where should I keep handoff notes for cloud agents?

Somewhere the cloud agent can reach over the network. Cursor's cloud agents can't read your local home directory, and Claude Code's auto memory isn't shared with cloud environments. A note served over MCP or a REST API, such as a LotsNotes note, reaches both local and cloud agents.

### How do I stop two agents overwriting the same handoff note?

Have each agent send the version it read when it saves. In LotsNotes, `save_context_note` with `expected_version` fails with a conflict if the note changed since, and every earlier version stays restorable.

## Sources

Checked on 22 October 2026:

- Claude Code docs: [Manage sessions](https://code.claude.com/docs/en/sessions) (resume, branch, export, transcript storage and retention, what a resume restores), [CLI reference](https://code.claude.com/docs/en/cli-reference) (`--continue`, `--resume`, `--name`, `--fork-session`, `--from-pr`, `--teleport`), [Commands](https://code.claude.com/docs/en/commands) (`/compact`, `/branch`, `/export`, `/import`), [Memory](https://code.claude.com/docs/en/memory) (CLAUDE.md, AGENTS.md, auto memory is machine-local), [Common workflows](https://code.claude.com/docs/en/common-workflows) and [MCP](https://code.claude.com/docs/en/mcp).
- Codex docs (linked from [developers.openai.com/codex](https://developers.openai.com/codex/llms.txt)): [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md), [Codex CLI commands](https://learn.chatgpt.com/docs/developer-commands?surface=cli) (`codex resume`, `codex fork`, `/compact`, `/import`), [Import from another agent](https://learn.chatgpt.com/docs/import), [Memories](https://learn.chatgpt.com/docs/customization/memories) and [MCP](https://learn.chatgpt.com/docs/extend/mcp).
- Cursor docs: [Rules](https://cursor.com/docs/rules), [MCP](https://cursor.com/docs/mcp), [Prompting](https://cursor.com/docs/agent/prompting) (`@Chats`, context summary), [Agent overview](https://cursor.com/docs/agent/overview) (side chats) and [Cloud agents](https://cursor.com/docs/cloud-agent).
- LotsNotes: [tool list](https://api.lotsnotes.com/tools.json), [API docs](https://api.lotsnotes.com/docs.md), [agent skill](https://lotsnotes.com/skill.md) and [setup guides](https://lotsnotes.com/mcp).