--- title: "How to coordinate Cursor and Claude Code on the same codebase · Cork" description: "Run Cursor and Claude Code on one repo without clobbered edits: shared AGENTS.md instructions, worktrees, shared MCP servers, hooks, and a coordination layer." canonical: "https://corkcli.com/blog/coordinate-cursor-and-claude-code-same-codebase" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # How to coordinate Cursor and Claude Code on the same codebase Run Cursor and Claude Code on one repo without clobbered edits: shared AGENTS.md instructions, worktrees, shared MCP servers, hooks, and a coordination layer. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 6 min read To coordinate Cursor and Claude Code on the same codebase, give both agents one shared instruction file (`AGENTS.md`), keep each agent on its own branch or git worktree so their edits cannot land on the same files at the same moment, connect both to the same MCP servers so they see the same tools, and use hooks to check work after every edit. What none of those steps does on its own is tell one agent what the other is changing right now; for that you need a [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) that both agents report to. ## Why Cursor and Claude Code collide Cursor's agent and Claude Code are separate programs with separate context windows. Neither reads the other's conversation, and neither knows the other just renamed a function. If both work in the same checkout, the usual failure looks like this: Claude Code edits `auth.ts`, Cursor's agent opened `auth.ts` a minute earlier, writes its own version from stale context, and one set of changes quietly disappears. Even when they never touch the same file, one agent can change a signature that the other is calling, and nobody finds out until the build breaks. The fix has three parts: shared instructions, separate working trees, and live awareness. ## Step 1: give both agents the same instructions Both tools read `AGENTS.md`. As of October 2026, Cursor's rules documentation describes `AGENTS.md` as "a simple markdown file for defining agent instructions" that you place in the project root as an alternative to `.cursor/rules`, with nested `AGENTS.md` files supported in subdirectories. Claude Code reads `AGENTS.md` as project instructions when there is no `CLAUDE.md` in the working directory or above it (this requires Claude Code v2.1.277 or later). If your repo already has a `CLAUDE.md`, put an import line at the top of it so Claude reads the shared file too: ```markdown @AGENTS.md ## Claude-specific notes - Run the test suite with `npm test` before finishing. ``` Keep the shared file short. Claude Code's docs recommend keeping each `CLAUDE.md` under 200 lines, because longer files cost context and reduce adherence. Put the things both agents must agree on in it: build and test commands, naming conventions, which directories are off limits, and a rule such as "never rewrite a file another agent has open without rereading it first". If you need Cursor-only rules (for example, a rule scoped to `*.tsx` files), put them in `.cursor/rules/` as `.mdc` files with `description`, `globs` and `alwaysApply` frontmatter. ## Step 2: separate the working trees The simplest guard against overwrites is to never let both agents write into the same directory. [Git worktrees](https://corkcli.com/blog/git-worktrees-parallel-ai-coding-agents) give each agent its own checkout of the same repository: ```bash git worktree add ../myapp-cursor -b cursor/search-filters git worktree add ../myapp-claude -b claude/billing-fix ``` Open `../myapp-cursor` in Cursor and start Claude Code in `../myapp-claude`. Claude Code can also create one for you: `claude --worktree billing-fix` creates `.claude/worktrees/billing-fix/` on a new branch named `worktree-billing-fix`. Add `.claude/worktrees/` to `.gitignore`. Clean up with `git worktree list` and `git worktree remove ../myapp-cursor` when the branch is merged. Worktrees stop agents from overwriting each other's files while they work. They do not stop conflicts at merge time: if both branches changed the same function, you still resolve it by hand, and if one branch renamed something the other calls, the merge can be clean and the build still broken. ## Step 3: connect both agents to the same MCP servers If one agent can query your issue tracker or database and the other cannot, they will make different assumptions. Configure the same servers in both: - Claude Code: `claude mcp add --transport http --scope project ` writes to `.mcp.json` in the repo root, which you can commit. - Cursor: add the same server to `.cursor/mcp.json` in the project root with a `url` field. See our guide to adding a remote MCP server to each tool for the exact formats. ## Step 4: check every edit with hooks Both tools now run hooks. [Claude Code hooks](https://corkcli.com/blog/claude-code-hooks-pretooluse-posttooluse-team-workflows) live in `.claude/settings.json`; a `PostToolUse` hook with the matcher `Edit|Write` runs after every file edit, for example to run a formatter or type check. Cursor hooks live in `.cursor/hooks.json` (with `"version": 1`) and include `afterFileEdit` and `beforeShellExecution` events. Run the same check script from both so that whichever agent breaks the build hears about it on its next step, not at review time. ## Step 5: decide who owns what Before starting, split the work by area, not by task title. "Cursor owns `web/components/search/`, Claude Code owns `api/billing/`" is enforceable. "Cursor does the frontend part" is not, because both agents will touch the shared types file. Write the split into the shared instruction file so both agents read it, and name any shared file (types, schema, config) that only one agent may change. ## How Cork helps Shared instructions and worktrees prevent most accidents, but neither agent knows what the other is doing right now. Cork fills that gap. Cork is the coordination layer for [multiplayer coding agents](https://corkcli.com/blog/multiplayer-coding-agents): it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. For a Cursor plus Claude Code setup, that means: - **Live awareness**: when Cursor's agent renames a function that Claude Code's work depends on, Claude Code hears about it on its next step. - **[Write gate](https://corkcli.com/blog/write-gate)**: an edit against code the other agent is changing right now is held until your agent has their version. - **Briefing**: when either agent starts or gets a prompt, it receives the exact signatures, callers and recent changes of the code it is about to touch. - **[Semantic lint](https://corkcli.com/blog/semantic-lint)**: a rename or signature change by one agent becomes a lint rule the other is checked against. It runs through hooks in Claude Code, Codex and Cursor with no extra model calls, and does not run or host your agents. Install it once for every repo on the machine: ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` Cork Free covers unlimited agents and repos on one machine with no account; seeing teammates' agents on other machines is the paid plan. ## Frequently asked questions ### Can Cursor and Claude Code work on the same repo at the same time? Yes. Both can open the same folder, but if they edit the same files concurrently one can overwrite the other. Use separate worktrees or a coordination layer that holds conflicting edits. ### Do Cursor and Claude Code share the same rules file? They can. Cursor supports `AGENTS.md` in the project root, and Claude Code reads `AGENTS.md` when there is no `CLAUDE.md`, or through an `@AGENTS.md` import inside `CLAUDE.md`. ### Does Cursor run Claude Code hooks? Cursor's hooks documentation says it supports loading hooks from third-party tools like Claude Code and points to a separate compatibility page. Check that page for which events map before relying on it. ### Will git worktrees stop merge conflicts between the two agents? No. Worktrees stop live overwrites while the agents work. Conflicts and broken references still surface when the branches merge. ## Sources - - - - - - - - ## Related reading - [How to run Codex and Claude Code side by side on one project](https://corkcli.com/blog/run-codex-and-claude-code-side-by-side): Run OpenAI Codex CLI and Claude Code on one repo: one AGENTS.md for both, a worktree each, shared MCP servers, matching hooks, and live coordination. - [How to share context between Codex and Claude Code](https://corkcli.com/blog/share-context-codex-claude-code): Make Codex and Claude Code work from the same context: one AGENTS.md, shared MCP servers, handoff files, and live awareness when both edit the same repo. - [MCP servers for coordinating coding agents: what they are and how to use one](https://corkcli.com/blog/mcp-servers-coordinating-coding-agents): What an MCP server for coordinating coding agents does, how it differs from hooks, and how to connect one to Claude Code, Codex, Cursor and Gemini CLI. - [Cork vs Zed (and Delta): an editor and a shared thread, or a coordination layer](https://corkcli.com/blog/cork-vs-zed): Cork vs Zed: Zed is an editor with external agents and Delta, a multiplayer agent environment on DeltaDB. Cork coordinates the agents you already run. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/coordinate-cursor-and-claude-code-same-codebase