agent-bridge

Let Claude Code and Cursor hand work to each other.

You pay for two AI coding subscriptions. Only one of them is working at a time. This bridge lets each one call the other, so the load spreads across both plans.

How it works, in plain English

Think of two contractors. Each one sends you a separate invoice.

Either contractor can hand the other a written brief and get an answer back. Neither one can read the other's notebook. The brief is all they get. And a brief cannot be handed on a second time, so the work cannot bounce forever.

That is the whole idea. Here are the parts that make it happen.

• The server. One small program that sits between the two tools. It speaks MCP, the standard both tools use to load extra abilities.

• Two tools. ask_cursor sends a job to Cursor. ask_claude sends a job to Claude Code. Each one runs the other program the way a script would, waits, and returns the answer.

• No shared memory. The other side sees only the text you send. It cannot see your chat. So the brief must stand on its own. This is the single most common cause of a bad result.

• A subagent, on the Claude side. A small helper that tells Claude when to hand execution to Cursor. You do not name the tool yourself.

• A rule, on the Cursor side. The same idea in reverse. Cursor asks Claude for plans and code reviews on its own.

• A depth guard. The bridge refuses a second hop. Claude can call Cursor. That Cursor cannot call Claude back. Without this, two agents can loop and drain both subscriptions.

• A log. Every call writes one line to ~/.agent-bridge/log.jsonl, so you can check whether the split is actually happening.

Related MCP server: Agents Council

Why you might want this

• Spread the cost. Execution burns the most tokens. Push it to the other plan and keep your main allowance for thinking.

• Two opinions. Different model families catch different mistakes. Useful for architecture calls and code review.

• Buy quality on the cheaper bill. Cursor can serve Claude models. Check with cursor-agent models. If yours does, ask_cursor with that model gives you Claude output billed to Cursor.

Be honest about the trade. Each call starts cold, so the other tool re-reads your code every time. You will spend more tokens in total. You are buying a split, not efficiency.

Requirements

• Node 18 or newer.

• Claude Code, logged in.

• Cursor CLI, logged in. The binary is cursor-agent. A bare agent on your PATH may be a different vendor's tool. Check with cursor-agent status.

You can install with only one of the two. The installer skips what it cannot find.

Install

git clone <this repo> agent-bridge
cd agent-bridge
./install.sh

Then do the three manual steps it prints. Restart both tools.

To remove it, run ./uninstall.sh.

The one permission you must grant

Claude Code blocks the bridge until you allow it. Without this you get a prompt on every single delegation, which defeats the purpose.

Add to permissions.allow in ~/.claude/settings.json:

"mcp__agent-bridge__ask_cursor"

The installer does not write this for you. It is a security decision, so you should make it yourself. Read the next section before you do.

What write mode does

Both tools default to plan mode, which is read only. Safe.

mode: "write" is different. On the Cursor side it runs cursor-agent --force. That means Cursor can edit your files and run shell commands with no confirmation.

Combine that with the permission above and there is no human check before the change happens. Your only gate is reading the diff afterwards. Always read the diff.

If that is too loose for you, leave the permission ungranted and approve each call by hand. You lose the automatic routing and keep the control.

Picking the right model

Cursor can run several model families: Claude, GPT and Codex, Gemini, Composer, Kimi and GLM. The model option passes an id straight through.

Never guess an id. The list changes. Call list_cursor_models first, or run cursor-agent models in a terminal.

Choose by job, not by habit.

Paying for a large model on a mechanical edit wastes the budget this bridge exists to protect. Omit model entirely to let Cursor choose for you.

Check the data retention label first

Some models in the list are marked (NO ZDR). That means no zero data retention: the vendor may keep what you send.

Do not route client code, customer data or anything under a confidentiality obligation through a NO ZDR model. If you work under ISO 27001 or a similar regime, check the label before you pass an id, every time. The list marks it plainly.

Tools

Both take the same options.

• task (required): the full brief. The other side sees nothing else.

• mode: plan (read only, the default) or write.

• model: optional passthrough, for example gpt-5.3-codex or claude-opus-5-thinking-high.

• cwd: working directory. Defaults to the server's directory.

• timeout_seconds: default 600, max 3600.

Writing a good brief

The other tool has no context. A vague brief costs more than a long one, because the work comes back wrong and you pay twice.

Include all five of these:

1. The repository root and the exact files in scope.

2. The change, stated as an outcome rather than a goal.

3. An existing file to copy the conventions from.

4. The command that proves it worked.

5. What it must not touch.

Automatic routing

You should never have to name a tool. Three pieces handle it.

What to delegate

The split is not coding versus everything else. It is what the other side can reach.

Send to Cursor: implementation and refactoring, tracing how a codebase works, reading or summarising many files, bulk and repetitive edits, data pulls and analysis through any MCP server both sides share, research, and a second opinion on any decision.

Keep in Claude Code: anything needing a tool or skill only it has. On a typical setup that means email, calendar and chat connectors, and any branded document generated by a Claude Code skill. Cursor has neither, and it will produce something that looks finished and is wrong.

Both installed rule files carry this split, so each side knows its own limits. Edit them to match your own tooling, because the exact list differs per machine.

This is instruction, not enforcement. The model decides. Only a PreToolUse hook would force it, and that hook would block ordinary work in every project. Check the log to see whether the routing is really happening.

The subagent runs on Haiku and holds a single tool, so its own cost is negligible. The real work happens inside Cursor.

There is also install/claude-md-snippet.md. Paste it into a project's CLAUDE.md if you want the rule in one repository only. Do not put it in your global CLAUDE.md, or you will push delegation into every project you own, including client work.

Reading the log

Every call appends one row to ~/.agent-bridge/log.jsonl. Override the path with AGENT_BRIDGE_LOG.

{"timestamp":"...","tool":"ask_cursor","mode":"write","model":null,"cwd":"...",
 "task_chars":333,"output_chars":0,"duration_ms":1281,"exit_code":1,"timed_out":false}

Cursor's CLI reports no token counts. So size and duration are the only in-band cost proxy. Read real spend from each vendor's dashboard.

python3 -c "
import json,collections,os
rows=[json.loads(l) for l in open(os.path.expanduser('~/.agent-bridge/log.jsonl'))]
c=collections.Counter(r['tool'] for r in rows)
print('calls:', dict(c))
for t in c:
    d=[r['duration_ms'] for r in rows if r['tool']==t]
    print(t, 'total minutes', round(sum(d)/60000,1))
"

Measuring whether it works

The metric is not dollars. Both plans bind on caps, not on spend. So measure the share of each cap you burn per unit of work delivered.

Run two weeks. Week one, one tool only, as a baseline. Week two, with routing on. Record each cap reading at the start and end, the log rows, and one quality gate: did the tests pass, and did you have to redo the work? If quality drops, the saving is not real.

Using it from the Cursor Agents browser

Cloud agents run in Cursor's own machines. Those machines have no Claude Code login. Using ask_claude there needs an API key, which bills the API instead of your subscription. That defeats the point.

Worker mode is the path. It runs the browser-launched agent on your own machine, where Claude Code is already signed in.

cursor-agent worker --pool --worker-dir ~/code/<one-repo>

Three rules:

• Scope --worker-dir to one code repository. Never your home directory.

• Use --pool, so one cloud agent claims the worker at a time.

• Copy the rule file and the agent-bridge entry from ~/.cursor/mcp.json into that repository's own .cursor/ directory. A worker-claimed agent may only read the repository config.

What is tested, and what is not

Restart both tools after installing

A Claude Code session that started before the install cannot see the new tools. The cursor-delegate subagent then fails with:

Agent 'cursor-delegate' would be spawned with zero tools
unrecognized [mcp__agent-bridge__ask_cursor]

That is not a broken install. Quit Claude Code and start it again. Same for Cursor.

What is tested

Tested on macOS with Claude Code and Cursor CLI 2026.08.11:

• The server, the two tools, and the self-test.

• ask_claude returning a real answer.

• Claude selecting the subagent on its own and reaching the bridge.

• The depth guard surviving a real Claude Code spawn.

Not yet tested:

• The Cursor rule firing without being asked.

• Whether the depth guard survives Cursor's own spawn. If Cursor drops the environment variable, a loop could run across both subscriptions. Check with: AGENT_BRIDGE_DEPTH=1 cursor-agent -p --trust "call the ask_claude tool with task hi"

• Whether worker mode is available on your Cursor plan. It looks like a Teams or Enterprise feature.

Reports welcome, especially from Linux and Windows.

Test

npm test           # fast checks only
LIVE=1 npm test    # adds a real Claude Code round trip

LIVE=1 calls Claude Code for real. Allow mcp__agent-bridge__ask_claude first, or approve the prompt when it appears.

Notes

• A Claude Code plugin could wrap the Claude half one day. It would not cover the Cursor half, so a script that does both is the honest unit for now.

• MIT licensed.