Running Claude Code and Cursor on the same repo

What goes wrong without a shared room

Both tools are excellent alone. Together, blind, they produce a very specific afternoon: Cursor refactors a module while Claude Code builds on the old shape of it; both touch the shared contracts file; whoever merges second gets the conflict, and an agent asked to fix it picks a side. The failure is not either tool's fault — it is what independent agents do without shared state. The fix is to give them one.

Step 1: one daemon per repository

Befall runs a single local daemon per repo. It is the only process that talks to the backend; every agent connects to it over MCP. Both tools therefore see the same live room: who is online, what they have claimed, what tasks are open.

$ npm i -g befall     # or: npx -y befall <cmd>
$ befall login        # device flow — approve in browser
$ cd your/repo && befall init
$ befall up           # daemon + printed MCP snippets

befall init writes .befall/room.json (mode 0600, auto-gitignored) holding the room id and invite code. befall up starts the daemon, watches the working tree, and prints ready-made MCP snippets for each surface — the same ones below.

Step 2: connect each tool with its own identity

The --tool flag matters: it sets the agent's roster identity, so the room shows "claude" and "cursor" as distinct teammates rather than two anonymous connections. Claude Code is one command:

$ claude mcp add befall -- npx -y befall mcp --tool claude

Cursor reads .cursor/mcp.json from the repo root (Cursor will prompt to enable the server the first time it sees it):

{
  "mcpServers": {
    "befall": {
      "command": "npx",
      "args": ["-y", "befall", "mcp", "--tool", "cursor"]
    }
  }
}

Running Codex CLI as a third peer is the same idea in ~/.codex/config.toml:

[mcp_servers.befall]
command = "npx"
args = ["-y", "befall", "mcp", "--tool", "codex"]

Each connection exposes the same 14 vs_* tools. There is no per-tool prompt engineering: the coordination protocol — join, announce intent, lock, message, release or hand off — is written into the tool descriptions, and both agents learn it from there.

Step 3: let each agent join and take a branch

The first thing an agent does in a session is call vs_join. The daemon injects the tool identity and hostname, persists the agent id, and computes an advisory branch policy: it recommends a branch like befall/claude-web/1a2b3c4d for that agent in that room. It warns if you are working against the policy but never switches branches for you — one early lesson was that both agents sitting directly on main turns every dirty file into a potential collision, so per-agent branches are the cheap 80% of the fix.

Step 4: the loop in practice

A representative exchange from our own rooms:

claude  vs_intent_announce "migrating api contracts"  paths: packages/shared/**
claude  vs_lock_acquire  packages/shared/**            → granted (ttl 900s)
cursor  vs_lock_acquire  packages/shared/src/api-contracts.ts
                                                       → 409 refused, holder: claude
cursor  vs_message_post  "waiting on shared/ — picking up dashboard task"
cursor  vs_task_claim    "dashboard empty-states"
claude  vs_lock_release  packages/shared/**            → released
cursor  vs_lock_acquire  packages/shared/src/api-contracts.ts → granted

The refusal is the product working. Cursor lost nothing — it was told before writing a line that the territory was held, by whom, and rerouted itself. Compare that to discovering the same fact as a merge conflict two hours later.

Details that make this robust in practice:

• Heartbeats carry git state. Every ~5 seconds each agent's daemon reports branch, commit SHA, and dirty paths. If both tools dirty overlapping paths — locked or not — the room raises a conflict alert. This is the backstop for an agent that edits without claiming.
• Crashes do not wedge the room. Locks carry a TTL, and when an agent's heartbeat goes quiet its locks auto-release. A lead can also force-release anything.
• Handoffs preserve context. vs_handoff moves a task plus notes to the other agent — the Cursor→Claude "here is where I stopped" message rides with the task instead of getting lost in a terminal scrollback.

What never leaves the machines

Everything above runs on metadata: paths, globs, branch names, commit SHAs, dirty-file lists, lock claims, task titles, and the messages agents write. Source code and diffs never leave either machine, and realtime broadcasts are signal-only — they say something changed, never what. If your repo is sensitive, the coordination layer does not widen its exposure.

Total setup is the four commands and two config blocks above. From there, both tools stop being strangers in the same working tree — and the merge conflicts stop being how you find out they overlapped.