Guides
CursorGit worktrees

Cursor worktrees and cloud agents: landing the pull requests

Cursor runs agents in git worktrees on your machine and in cloud VMs that push branches. See how both work and how to keep the pull requests landing.

Cursor isolates local agents in git worktrees and runs cloud agents in their own VMs, each on a separate branch. Bring worktree results back with /apply-worktree or a pull request, let cloud agents push their branches, and put a merge queue that resolves conflicts in front of main.

Worktrees in Cursor

Cursor creates a separate checkout for an agent so several agents can work on one repository. In the Agents Window, start or move an agent into a worktree. In the editor, use the worktree commands. See the Cursor worktree docs.

/worktree fix the failing auth tests and update the login copy
/best-of-n sonnet,gpt,composer fix the flaky logout test
/apply-worktree
/delete-worktree

Cursor keeps up to 25 worktrees per machine by default and cleans up the oldest.

Set up new worktrees automatically

A worktree is a fresh checkout, so it needs dependencies and local configuration. Put the commands in .cursor/worktrees.json and Cursor runs them in each new worktree:

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Use setup-worktree-unix and setup-worktree-windows when the commands differ by platform. The docs recommend a fast package manager over symlinking dependencies into the worktree.

Cloud agents

Cloud agents, formerly Background Agents, run in isolated VMs in the cloud. Each works on a separate branch and pushes its changes to your repository, and the docs say you can run as many as you want in parallel. Start one from the Cloud option under the agent input, from cursor.com/agents, or by commenting @cursor on a GitHub pull request or issue. See the Cursor cloud agent docs.

Local worktree or cloud agent

Local worktreeCloud agent
Where it runsOn your machine, in a separate checkoutIn an isolated VM in the cloud
How work comes back/apply-worktree, or a commit and pull request from the worktreeA separate branch pushed to your repository
Good forTasks you want to compare or review locallyTasks that run while your machine is busy or off

A workflow for several Cursor agents

  1. Give each agent one task with a clear boundary, and start it in a worktree or as a cloud agent.
  2. Use /best-of-n when you want to compare models on one task. It compares runs and merges nothing, so pick the result you want afterwards.
  3. Review each result where it ran, then commit, push and open a pull request for it.
  4. Remove finished worktrees with /delete-worktree, or let Cursor clean up the oldest.
  5. Land the pull requests through a merge queue, so no agent has to update its branch by hand.

Where the pull requests collide

Whether an agent ran in a local worktree or a cloud VM, its branch started from one commit of main. Once another pull request lands, that branch is behind. Edits to the same lines become merge conflicts. Edits to related code, such as a renamed function and a new call to its old name, merge cleanly and break the build. The more agents you run at once, the more often a landing sends the others back for repair.

Landing the pull requests

Keep each agent’s pull request to one task, run your required checks on the combined result, and put a merge queue in front of main. Merget is a semantic merge queue for GitHub. It finds the pull requests that collide, including the ones Git merges cleanly, resolves the conflicts in queue order, and lands the result through your required checks and reviews.

Merget works from GitHub, so nothing changes in how Cursor works. Merget starts in Advisory mode, where it reports the conflicts and changes no source code. To give your agent the queue’s findings and order, paste this into it:

Fetch and execute the instructions to set me up for Merget from https://sema.merget.ai/agent-setup/prompt.md

What changes with a queue that resolves conflicts

Without one, every landing sends other agents back to update their branches. With one, an agent is finished when its pull request is open, and the queue reconciles the pull requests. In our benchmarks, Merget planned a queue of 40 merges in under 30 seconds and resolved 223 of 223 conflicted files from real merges with one model call each.

Using Claude Code or Codex as well? See the Claude Code worktrees guide and the Codex worktrees guide.

Questions

How do I run a Cursor agent in a worktree?

Use /worktree <task> in the editor, or start or move an agent into a worktree from the Agents Window.

How do I bring worktree changes back into my checkout?

Run /apply-worktree, or commit and push from the worktree and open a pull request.

Do Cursor cloud agents open pull requests?

Each cloud agent works on a separate branch and pushes it to your repository for handoff as a pull request.

See how Merget resolves conflicts in queue order, or sign up free and connect one repository.