Cursor Parallel Agents: 12 Steps, 70 Min A 2026 Cursor vs Copilot comparison reports that Cursor 3's Agents Window runs agents in parallel across local worktrees, cloud environments and remote SSH, but does not prevent concurrent agents from editing the same file. The comparison's companion build guide describes a roughly 70-minute Python tool, agentfleet, that assigns one git worktree per task, warns about overlapping paths before agents start, tests every pair of branches for merge conflicts and assembles clean branches onto an integration branch. The 2025 Stack Overflow Developer Survey found 31% of developers already use AI agents at work, and 69% of those users agree the tools raised their productivity. Cursor 3 introduced an Agents Window that runs agents in parallel across local worktrees, cloud environments and remote SSH, according to a 2026 Cursor vs Copilot comparison https://www.getmaxim.ai/articles/cursor-vs-copilot/ that tracks the release. The window makes it easy to start four agents at once. It does nothing to stop those four agents from editing the same file, and that is where most parallel Cursor agents runs go wrong. Cursor agents are fast enough now that the bottleneck moved from typing to merging. You can brief one agent on a feature, another on tests and a third on docs, then walk away for twenty minutes. If all three work in the same checkout, they overwrite each other, stage each other’s half-finished files and leave you a diff nobody can review. A git worktree gives each agent its own folder and its own branch while sharing one object store, which is why Cursor builds its parallel mode on top of them. You will build a small Python tool called agentfleet that sets up one worktree per task, warns you about overlapping paths before any agent starts, reports progress, tests every pair of branches for merge conflicts and assembles the clean ones onto an integration branch. It sits next to Cursor rather than replacing anything, so it works the same whether you launch agents from the Agents Window, the editor chat or custom subagents https://shattered.io/cursor-subagents-custom-agents-verifier-12-steps-2026/ inside a single session. The whole build takes about 70 minutes and every command below was run against a real repository. Don't miss new tech stories on Google Add Shattered once in the Google app and our stories show up in your news suggestions. Add now https://www.google.com/preferences/source?hl=en&q=https%3A%2F%2Fshattered.io%2F Why Parallel Cursor Agents Collide Without Isolation Three failure patterns show up again and again when people run several agents against one working directory. The first is file clobbering. Agent A rewrites src/cart/cart.py , agent B opens the same file a minute later with a stale mental model and saves its own version on top. Neither agent reports a problem because, from each one’s point of view, the write succeeded. The second pattern is index pollution. Git has a single staging area per checkout. If one agent runs git add -A while another is mid-edit, the first agent’s commit sweeps in the second agent’s half-written changes. You end up with a commit message about discounts and a diff that also contains a broken tax function. Reverting one task means untangling the other. The third pattern is slower to notice: shared state outside git. Two agents that both start a dev server fight over port 3000. Two agents that both run a test suite against the same SQLite file corrupt each other’s fixtures. A branch-per-agent habit does not fix any of this, because branches do not change the files on disk. Only separate directories do. Demand for this workflow is real. The 2025 Stack Overflow Developer Survey found that 31% of developers already use AI agents at work, and 69% of those who have used them agree the tools raised their productivity, per the survey’s press release https://stackoverflow.co/company/press/archive/stack-overflow-2025-developer-survey/ . As those numbers climb, the pain moves from whether an agent can write the code to whether you can safely run more than one. Pricing pressure adds to it, since each extra agent burns usage. If you are weighing how many agents your plan can feed, the Claude Code vs Cursor vs Copilot pricing and limits breakdown https://shattered.io/claude-code-vs-cursor-vs-github-copilot-pricing-limits-2026/ covers the usage side. Isolation alone is not enough, though. Even with perfect worktrees, two agents can both be correct in their own folders and still produce changes that collide at merge time. That is why the tool you build here has a planning step before launch and a conflict check after. The first catches overlap you can see coming. The second catches the overlap you could not. Prerequisites: Tools, Versions and Accounts The project uses only the Python standard library and plain git, so setup is short. The one version that matters is Git. The conflict check relies on git merge-tree --write-tree , a mode of the command that performs a real three-way merge in memory without touching any working directory. Older Git releases only had a legacy form of merge-tree with a different interface. The table lists what the walkthrough was tested on. | Requirement | Version used | Why it matters | |---|---|---| | Git | 2.43.0 tested, 2.38 or newer needed | 2.38 added merge-tree --write-tree , which the conflict check calls | | Python | 3.12.3 tested, 3.8 or newer works | Script uses f-strings, pathlib and subprocess.run only | | Cursor | 3.24 or newer | Release notes tie the cloud-to-local worktree handoff to 3.24 | | Operating system | Linux tested | macOS and Windows run the same script, paths use pathlib | | Disk space | Your repo size per worktree | Each worktree has a full working tree, history is shared | | Cursor account | Any plan for local agents | Cloud agents need a paid plan with cloud agents enabled | Check your Cursor version from the About dialog before you start, because the Agents Window changes quickly. Cursor’s release notes put the ability to move a cloud agent into an existing or new local worktree, without touching your main checkout, in version 3.24. If your build is older, everything here still works for local worktrees. You only lose the handoff feature covered in the advanced section. You also need a repository you can safely experiment on. The tutorial creates a throwaway one called shop so you never risk real work. When you move to a real project, start with a clean working tree and a base branch that builds. An agent that starts from a broken base produces a fleet of branches that all fail for the same unrelated reason. Cursor Agents Window, Worktrees and Cloud Agents Compared Cursor offers several places to run an agent, and picking the wrong one for a task is a common source of confusion. The Agents Window, introduced with Cursor 3, can host parallel agents on local worktrees, in cloud environments and over remote SSH. It also added a /worktree command, per the same 2026 comparison. Each mode trades isolation, speed and reach differently. | Mode | Where it runs | Isolation | Best for | Main limit | |---|---|---|---|---| | Local, in place | Your checkout | None | One quick task | Collides with your own edits | | Local worktree | Separate folder on your machine | Own branch and files | Parallel tasks in one repo | One Git repository per local session | | Cloud agent | Remote sandbox | Full VM | Long jobs, several repos | Needs a paid plan with cloud agents enabled | | Remote SSH | Another machine | Depends on setup | Heavy builds, GPU boxes | You manage the host | Two details from Cursor’s documentation shape how you plan work. First, local Agents Window worktrees cover a single Git repository. A multi-root workspace does not run its projects in parallel, so cross-repository coordination belongs to Cursor cloud agents https://shattered.io/build-cursor-cloud-agents-2026/ , whose environments support up to 300 repositories. Second, language servers are off by default inside Agents Window worktree workspaces for performance, though you can switch them back on. Expect fewer inline diagnostics in those windows until you do. Where do the worktrees live on disk? Community reports say Cursor creates its own under ~/.cursor/worktrees , but that comes from forum users rather than an official release note, so treat it as likely rather than guaranteed. The tool in this tutorial sidesteps the question by creating worktrees in a folder you choose, next to the repository, then letting you open them in Cursor like any other folder. That choice has a practical upside. Because agentfleet owns the worktree lifecycle, it can check conflicts across branches and clean up deterministically, which the editor’s built-in flow does not promise to do for you. Use Cursor’s own worktree button when you want convenience and use this tool when you want a repeatable fleet with a merge gate. Nothing stops you from mixing the two. Phase 1: Prepare the Repository Steps 1-3 Step 1: Check Git and Python versions Confirm both tools before writing code. A Git older than 2.38 is the single most likely cause of a confusing failure later, so catch it now. git --version python3 --version git worktree list Expected output on the test machine was git version 2.43.0 and Python 3.12.3 . The third command prints your current repository’s worktrees, and outside a repository it simply errors, which is fine for now. If Git reports a version below 2.38, upgrade it through your package manager or from the project’s site before continuing. The official git-worktree documentation https://git-scm.com/docs/git-worktree lists every subcommand this tool relies on, including add , remove and prune . Step 2: Create the demo repository The demo repo is a tiny shop with four areas that map to four tasks: a cart module, an auth module with tests, a docs folder and a future tax module. Keeping the layout small makes the conflict output easy to read. mkdir -p /tmp/fleet-demo/shop && cd /tmp/fleet-demo/shop git init -q -b main . git config user.email email protected git config user.name "You" mkdir -p src/cart src/auth tests/auth docs printf 'def total items :\n return sum i "price" for i in items \n' src/cart/cart.py printf 'def login user :\n return True\n' src/auth/login.py printf 'def test login :\n assert True\n' tests/auth/test login.py printf ' Shop\n\nVersion 1\n' docs/README.md git add -A && git commit -qm "init" The -b main flag pins the initial branch name so the rest of the commands match your terminal regardless of your global Git defaults. If your default branch is master or trunk , either keep -b main here or change the base value in the next step. Step 3: Describe the fleet in fleet.json The config file is the contract between you and your agents. Each task gets an id, the paths it is allowed to touch and the prompt you will paste into Cursor. Declaring paths up front is the cheap half of conflict control. It forces you to decide ownership before any agent starts, and the same boundaries can later feed Cursor rules and AGENTS.md files https://shattered.io/cursor-rules-linter-agents-md-cursorignore-12-steps-2026/ that tell each agent where it may work. { "base": "main", "worktree dir": "../fleet-worktrees", "tasks": {"id": "cart-discount", "paths": "src/cart/" , "prompt": "Add a percentage discount to total in src/cart/cart.py."}, {"id": "auth-tests", "paths": "tests/auth/", "src/auth/" , "prompt": "Add failing-login tests."}, {"id": "docs-refresh", "paths": "docs/" , "prompt": "Rewrite docs/README.md."}, {"id": "cart-tax", "paths": "src/tax/" , "prompt": "Add tax to total and put helpers in src/tax/."} } Save that as fleet.json in the repository root and commit it. The worktree dir value is relative to the repo, so ../fleet-worktrees puts all agent folders beside your project and keeps them out of its tree. Task ids become folder names and branch names, so the loader you write next restricts them to lowercase letters, digits and hyphens. A prompt like the one for cart-tax deliberately names its own folder, which gives the agent a reason to stay out of the cart module. Phase 2: Build the Fleet Manager in Python Steps 4-7 Step 4: Write the git wrapper, config loader and path check Create agentfleet.py in the repository root. The first block holds imports, one thin wrapper around the git command line and the config loader. Every git call in the tool goes through git , which captures output and exits with a readable message when a command fails. That keeps the rest of the script free of try/except clutter and means a failure always shows the exact git error. bash /usr/bin/env python3 """agentfleet: one git worktree per Cursor agent, with conflict checks.""" import argparse import json import re import subprocess import sys from itertools import combinations from pathlib import Path ID RE = re.compile r"^ a-z0-9 a-z0-9- {1,40}$" def git args, cwd=None, check=True : proc = subprocess.run "git", args , cwd=cwd, capture output=True, text=True if check and proc.returncode = 0: sys.exit f"git {' '.join args } failed: {proc.stderr.strip }" return proc def repo root : return Path git "rev-parse", "--show-toplevel" .stdout.strip def load config path : cfg = json.loads Path path .read text seen = set for task in cfg "tasks" : if not ID RE.match task "id" : sys.exit f"bad task id: {task 'id' r} use a-z, 0-9, hyphens " if task "id" in seen: sys.exit f"duplicate task id: {task 'id' }" seen.add task "id" cfg.setdefault "base", "main" cfg.setdefault "worktree dir", "../fleet-worktrees" return cfg def wt path root, cfg, task : return root / cfg "worktree dir" / task "id" .resolve def branch of task : return f"agent/{task 'id' }" def norm p : return p.strip "/" + "/" def paths overlap a, b : return any norm x .startswith norm y or norm y .startswith norm x for x in a for y in b Two small decisions deserve a closer look. The id pattern rejects uppercase letters, spaces and slashes because the id doubles as a folder name and as the tail of a branch name like agent/cart-tax . A slash in the id would silently create a nested folder and a nested ref. The norm helper appends a trailing slash before comparing paths, so src/cart/ and src/cart/cart.py count as overlapping while src/cart/ and src/cartography/ do not. Without that slash, a plain startswith check would flag the second pair as a clash. Step 5: Add the plan and up commands Next come the first two commands, plus the status helper you will need in the following step. plan is a dry run that never touches git. It lists each task with its paths and exits with code 1 if any two tasks declare overlapping ones. up creates the worktrees. For each task it runs git worktree add -b agent/