How do I use Cursor and Claude Code together?
Run Claude Code inside Cursor, keep one set of rules both agents read, give each its own branch, and hand work across with a note. Step by step.
Run Claude Code in Cursor's integrated terminal, put your project rules in one AGENTS.md that both read, and give each agent its own branch or worktree so they never edit the same files at once. Cursor reads AGENTS.md as plain project instructions, and Claude Code reads it through a one-line CLAUDE.md that imports it. When work moves from one agent to the other, pass a short note with the branch, the last commit and what is left.
Plenty of developers use both: Cursor for editing with its inline and tab completions, Claude Code for longer tasks in the terminal. The friction is not running them side by side. It is keeping them from disagreeing.
Step 1: run Claude Code inside Cursor#
Cursor is built on VS Code, so Claude Code works in its integrated terminal:
claudeStarted there, Claude Code detects the editor and can install its editor integration, which shows its proposed edits as diffs in Cursor. Run /terminal-setup once so Shift+Enter adds a new line in the terminal prompt.
Step 2: one set of rules for both agents#
Each agent has its own rules file, and they drift apart within a week if you keep two. Keep one:
| File | Read by | Put in it |
|---|---|---|
AGENTS.md | Cursor, Codex, OpenCode and others | The real rules: commands, conventions, folders not to touch |
CLAUDE.md | Claude Code | One line: @AGENTS.md |
.cursor/rules/*.mdc | Cursor only | Rules scoped to paths, if you need them |
Cursor's rules docs describe AGENTS.md as a plain-markdown alternative to .cursor/rules. Project .mdc rules still work beside it for Cursor-only, path-scoped instructions.
Step 3: share tools, not secrets#
Both agents can use MCP servers, but each keeps its own config: Cursor in .cursor/mcp.json, Claude Code in .mcp.json at the project root. Commit both if the team should share the servers, and read keys from environment variables in both. A server's key in a committed file is a published key.
Step 4: one task per agent, one branch per task#
Running both agents on the same files at the same time is how you get half-applied edits. Split by task:
git worktree add ../app-billing -b billing
cd ../app-billing && claudeKeep Cursor on the main checkout for the task in front of you, and let Claude Code work the longer task in its worktree. Before starting, write down who has which task, even in a TASKS.md. Stopping agents from editing the same files covers the failure modes.
Step 5: hand work across with a note#
When one agent stops and the other continues, it should not have to rediscover the work. Ask the finishing agent for a handoff:
Write a handoff for another agent: the branch, the last commit, what is done, what is next, and any decision it must not undo.Paste that into the other agent, or keep it in the pull request description where both can read it.
What changes when it is a team?#
On one computer, the steps above are enough. With teammates, the same questions get harder: one person's Cursor and another's Claude Code cannot see each other's tasks, decisions only travel by commit, and handoff notes get pasted into chat.
Joxo puts each teammate's agent, Cursor, Claude Code, Codex, OpenCode and more, into one shared project. Each runs on its own person's computer and plan. The agents share a task board where only one agent can hold a task, decisions that reach every agent, and handoffs that carry the branch, the commit and the note. Setup is one line pasted into each agent, in the project folder:
Read https://joxo.ai/skill.md and follow it to set up Joxo in this project.Joxo with Cursor and Joxo with Claude Code show what each agent gets.
Frequently asked questions#
Does Cursor read CLAUDE.md?#
Cursor's documented project instructions are .cursor/rules and AGENTS.md. Keep the shared rules in AGENTS.md and let CLAUDE.md import it, so both agents read the same text.
Can Cursor and Claude Code edit the same branch?#
They can, but not at the same time. Finish and commit with one before the other starts, or give each its own worktree.
Do I need two subscriptions?#
Yes. Cursor and Claude Code are billed separately, each on its own plan. Nothing here asks you to share an account.
Which one should do the big task?#
Whichever you trust more for it. A common split is Claude Code for long tasks in the terminal and Cursor for edits you watch, but the setup above works in either direction.