How to hand off work from Cursor to Claude Code

People move work from Cursor to Claude Code all the time: Cursor for editing in the IDE, Claude Code for a long run in the terminal, or the other way round. The switch loses everything that isn't written down. Claude Code hasn't seen the Cursor chat, so it doesn't know what you tried or why the obvious fix is wrong. Three things make the switch clean: rules both tools read, a commit as the starting point, and a short handoff note.

Do Cursor and Claude Code read the same rules?#

Not by default. Cursor reads project rules from .cursor/rules/ and also reads an AGENTS.md at the root of the project. Claude Code reads CLAUDE.md. A project with rules only in .cursor/rules/ gives Claude Code nothing.

The simplest fix is one shared file. Move the rules both tools need (test commands, naming, folders to leave alone) into AGENTS.md, and make CLAUDE.md import it:

@AGENTS.md

## Claude Code only
- Use plan mode for changes under src/billing/.

Cursor reads AGENTS.md; Claude Code reads the same file through the import. Keep .cursor/rules/ for rules that only make sense in the editor, such as rules scoped to file patterns. The test is simple: if a rule should hold no matter which tool is typing, it goes in AGENTS.md.

How do I hand off the work itself?#

Start from a commit, not from unsaved edits. Cursor's changes sit in your working tree; if Claude Code runs in a different folder or worktree, it doesn't see them. Commit and push first:

git status --short
git add src/export/ tests/export.test.ts
git commit -m "wip(export): streaming works, quoting bug open"
git push -u origin feat/csv-export
git rev-parse --short HEAD

A work-in-progress commit is fine; squash it when the work lands. The short hash gives both tools one fixed point.

Then write the note. Ask Cursor's agent to draft it before you close the chat, while it still knows what happened:

Write a handoff note for the next agent. Include the branch and commit,
the goal in one sentence, what works and what doesn't, the single next
step, the exact command that proves it, decisions made and why, and
anything tried that failed. Under 200 words. Don't summarise the chat.

A good note looks like this:

## Handoff: CSV export
Branch feat/csv-export at a41c9e2.
Goal: GET /orders.csv streams all orders under 200 MB of memory.
Works: streaming, 1M rows in the benchmark.
Broken: cells with commas aren't quoted (failing test below).
Next: fix escapeCell in src/export/csv.ts.
Verify: npm test -- export
Tried, failed: buffering the whole file; ran out of memory at 300k rows.

Check it for claims nobody verified, such as "tests pass" after the last edit, then paste it into Claude Code as the first message, or put it in the description of a draft pull request so a reviewer sees it too.

How do I know Claude Code picked it up?#

Before it edits anything, ask it two things: the next step in its own words, and the result of the verify command. If the test doesn't fail the way the note says, the note or the checkout is wrong, and you find out in a minute instead of after twenty minutes of edits. If Claude Code restates the plan and breaks a rule, that rule is missing from AGENTS.md; add it once and both tools follow it from then on.

To see what changed since the handoff when you go back to Cursor:

git diff --stat a41c9e2..HEAD

What usually goes wrong?#

Three mistakes cause most bad switches:

1. Handing off a dirty tree. Claude Code starts in another worktree, doesn't see the edits, and rebuilds what Cursor already wrote. Commit first, every time.
2. A note that tells the story. "We looked at the exporter and tried a few things" gives Claude Code nothing to act on. One next step and one command beat a paragraph.
3. Rules in one tool only. A rule that lives in .cursor/rules/ and nowhere else is a rule Claude Code breaks. When Claude Code gets something wrong that Cursor gets right, look there first.

What about OpenCode or Codex?#

The same pattern works. OpenCode and Codex both read AGENTS.md, so the shared file reaches them without any import. The commit and the note don't care which tool reads them. How to connect Codex and Claude Code covers that pair in more detail.

When the next agent belongs to someone else#

Everything above works when you switch tools at one desk. When the work moves to a teammate's agent, the note has to travel too: through a pull request, a chat message, or a paste. Joxo carries the branch, the commit and the note into the receiving agent's next turn, whichever agent that person uses, and the team sees the handoff on one board. See Joxo with Cursor and Joxo with Claude Code.

Frequently asked questions#

Does Claude Code read Cursor rules?#

No. Claude Code reads CLAUDE.md, not the files in .cursor/rules. Put the rules both tools need in AGENTS.md, which Cursor reads, and add a line to CLAUDE.md that imports AGENTS.md. Then both tools follow one set of rules.

Can Claude Code see my Cursor chat history?#

No. Each tool keeps its own conversation. Anything Claude Code needs from the Cursor session has to be written down: in a commit, a handoff note or the pull request. Ask Cursor's agent to draft the note before you close the chat.

Do I need to commit before switching from Cursor to Claude Code?#

If both run in the same folder, Claude Code can see uncommitted edits, but a commit is still safer: it is a fixed point you can return to, and it works when Claude Code runs in another worktree or on another machine. Push the branch so nothing lives only on one laptop.

How do I move work from Claude Code back to Cursor?#

The same way in reverse: commit and push, ask Claude Code for the handoff note, open the branch in Cursor and paste the note into the chat. Run the verify command first, so you know the starting state is what the note says.