The Agents Window in Cursor: running parallel agents

The Cursor Agents Window is the Cursor 3.x view for running and watching several agents at once, whether they work on separate tasks or on child tasks of one larger plan you coordinate. It pays off only when each agent has an isolated checkout (a worktree or a cloud agent), a written task card and evidence a machine can check.

This page is for developers who already use Cursor’s agent and now want three or four of them working at the same time. You start an agent on the billing bug, a second on the flaky test, a third on the settings page. Twenty minutes later one is waiting for an answer you never saw, two have edited the same helper, and the third reports “done” with a diff you have no time to read. The window made starting agents easy. Supervising them is the part you have to design.

What you get from this workflow

• A decision table for when to run agents in parallel, when to run one task several ways, and when one coordinated run fits.
• A task card and two copy-paste prompts that make every agent report in the same seven-field status block, so you triage by status instead of by reading.
• Three shell checks that decide whether an agent’s branch is ready to merge: scope, overlap with other branches, and the gates.
• A merge order that keeps parallel branches from breaking each other.
• A project brief with a whole-run acceptance test, for a plan you approve in Plan Mode and then split across agents yourself.

What Cursor documents and what this page relies on

This page names no buttons, menus or keyboard shortcuts in the Agents Window. It relies on the building blocks Cursor’s documentation stated when it was checked on 28 August 2026.

Feature	What Cursor documents	Last checked	What this page assumes
Agents Window	Cursor documents it at cursor.com/docs/agent/agents-window; this page does not rely on its wording	28 August 2026	A place to start, watch and answer several agents. The workflow below does not depend on where in the UI you start an agent
Worktrees	“Worktrees let Agent work in isolated Git checkouts.”	28 August 2026	Each local agent gets its own branch and directory
Cloud Agents	Cloud agents “run in isolated VMs in the cloud with full development environments instead of on your local machine.”	28 August 2026	The alternative when a task needs a full environment or runs longer than your laptop stays open
Subagents	“Subagents are specialized AI assistants that Cursor’s agent can delegate tasks to.”	28 August 2026	One agent can split its own work; this page is about you running several top-level agents
Projects	Not verified: we could not confirm from Cursor’s documentation that a feature by this name ships, nor its behaviour, limits or plan availability	not verified as of 2 October 2026	Nothing. The brief and acceptance test below are for a coordinated run you split yourself

If your build differs, trust your build and keep the workflow: isolation, a task card, evidence and merge order do not depend on where the buttons are.

When should you run Cursor agents in parallel?

Run agents in parallel when the tasks are independent and each one has a check a machine can run. Parallelism multiplies what you have to verify, so the limit is your ability to check results, not Cursor’s ability to start agents.

Situation	Run it as	Isolation	You decide by
Three unrelated fixes in different modules	Parallel agents, one per task	One worktree each	Each branch’s gates and scope check
One hard task with several plausible designs	The same task card run two or three ways	One worktree each	The same tests on every attempt, then the smaller diff
A feature or migration that spans many steps, or several repositories	A coordinated run: one approved plan, one agent per child task	One worktree or cloud agent per child task	The whole-project acceptance test, after every child pull request
Two tasks that touch the same files	One agent, in sequence	One worktree	Not parallel work: overlap guarantees a merge conflict
A task you cannot describe in five acceptance criteria	Not yet parallel	None	Plan it first in Plan Mode

Start with two agents, not five. The Faros AI AI Engineering Report 2026 (April 2026, telemetry from 22,000 developers at Faros customers) found median time in review up 441.5% and 31.3% more pull requests merging without any review. More agents feed the same queue. Scale the count when your checks, not your reading, can keep up.

Run parallel agents from the Agents Window

1. Make the base branch green before you fan out. Every agent inherits the state of its base. Run your gates on it in the terminal first:

   git switch main && git pull --ff-only
   npm run typecheck && npm run lint && npm test

   A red base means every agent spends its first minutes on a failure that is not its task, and each “fix” conflicts with the others.

2. Put environment setup in the repository, not in your head. A fresh worktree has no node_modules, no .env.local and no local database. Commit one script every agent runs first, for example scripts/agent-setup.sh, that installs dependencies, copies .env.example to .env.local with local-only values and starts disposable services. Never copy production credentials into a worktree or a cloud agent.

3. Write one task card per agent. The card is the agent’s contract and your review checklist. Keep it to the goal, the files it may touch, the acceptance criteria and the command that proves them. See acceptance criteria an agent cannot misread for how to write the criteria.

4. Start each agent with its own isolated checkout, a worktree or a cloud agent, and paste its task card with the launch prompt below. Name each local branch agent/<task>, such as agent/eu-reverse-charge; the overlap check below finds branches by that prefix, so if Cursor or your cloud agents name branches another way, change the prefix in the check. Where in the UI you start it does not change the workflow. Choose a cloud agent when the task needs services your laptop does not run, or when it will outlast your session; cloud agents and Automations in Cursor covers environments and Builds.

5. Triage on a fixed rhythm, not on every notification. Every 20–30 minutes, ask each agent for the status block with the second prompt and sort them: blocked (answer now), running (leave alone), ready (run the merge checks), stuck (stop and rewrite the card).

6. Merge one branch at a time, with the checks in the next section, and rebase the others after each merge.

Copy-paste prompt: launch an agent from a task card

You are one of several agents working on this repository at the same time.
Work only on the task card below, in this worktree and branch.

TASK CARD
Goal: Invoices for EU customers show the reverse-charge note when the buyer has a valid VAT ID.
Files you may change: src/billing/invoice/**, tests/billing/invoice/**
Files you must not change: anything else, including shared utils, config, lockfiles and CI.
Acceptance criteria:
1. A buyer with a valid EU VAT ID outside the seller's country gets the note "Reverse charge: VAT to be accounted for by the recipient".
2. A buyer in the seller's own country never gets the note.
3. A buyer without a VAT ID never gets the note.
4. Existing invoice tests still pass unchanged.
Proof command: npm test -- tests/billing/invoice && npm run typecheck

Rules:
- Run scripts/agent-setup.sh before anything else.
- Write the test for criterion 1 first and show it fails; tests for criteria 2-3 are guards and must pass both before and after your change.
- If you need to change a file outside your allowed paths, stop and ask. Do not work around it.
- Do not edit, skip or weaken an existing test to make it pass.
- When done, commit on this branch and print this status block, one field per line: STATUS (BLOCKED, RUNNING, READY or STUCK), BLOCKED_ON (your question, or "none"), CRITERIA (each criterion with PASS, FAIL or NOT_RUN and the test that proves it), PROOF (the proof command and its final 10 lines of output), FILES (output of `git diff --stat main...HEAD`), OUTSIDE_SCOPE (any file changed outside the allowed paths, or "none"), NEXT (the one next step, or "none").

The allowed-paths line does two jobs. It keeps agents out of each other’s files, and it gives you a check you can run without reading the diff.

Copy-paste prompt: status block for triage

Stop after your current step and report in exactly this format, nothing else:

STATUS: one of BLOCKED | RUNNING | READY | STUCK
BLOCKED_ON: the question you need answered, or "none"
CRITERIA: each acceptance criterion with PASS, FAIL or NOT_RUN and the test that proves it
PROOF: the command you ran last and its final 10 lines of output
FILES: output of `git diff --stat main...HEAD`
OUTSIDE_SCOPE: any file you changed outside the allowed paths, or "none"
NEXT: the one next step you will take, or "none"

If you have tried the same fix three times without the proof command passing, report STUCK and explain what you tried.

How do you know a parallel agent’s branch is ready to merge?

“READY” is the agent’s claim. The checks below turn the claim into evidence you can trust without reading every changed line. Run them in the terminal from the main checkout.

1. The agent stayed in scope. The allowed paths from the task card become a filter; any output is a file the agent had no permission to touch:

git diff --name-only main...agent/eu-reverse-charge \
  | grep -vE '^(src/billing/invoice/|tests/billing/invoice/)'

2. No two branches touch the same file. Run this across every agent branch, local and pushed, before you merge the first one. It fetches first, so branches that cloud agents pushed to origin are included:

git fetch --prune origin
for b in $(git for-each-ref --format='%(refname:short)' refs/heads/agent/ refs/remotes/origin/agent/); do
  git diff --name-only main..."$b" | sed "s|^|${b#origin/} |"
done | sort -u | sort -k2 | awk '{ if ($2 == last) print prev "\n" $0; last=$2; prev=$0 }' | uniq

Any line printed is a file changed on two branches. Merge one of them, rebase the other and run its gates again, or give the second task back to a single agent.

3. The gates pass on the branch, not in the agent’s summary. Check the branch out in a throwaway detached worktree and run the same commands CI runs: type check, lint, tests. Then confirm the new test for criterion 1 can fail: revert the implementation files and run the tests again. Do not git switch to the branch: Git refuses to check out a branch that the agent’s worktree already holds, and working inside that worktree would change files under a running agent.

git worktree add --detach ../verify-eu agent/eu-reverse-charge && cd ../verify-eu
scripts/agent-setup.sh
npm run typecheck && npm run lint && npm test
git restore --source=main --staged --worktree -- src/billing/invoice/
npm test -- tests/billing/invoice   # the criterion 1 test must fail now
git restore --source=HEAD --staged --worktree -- src/billing/invoice/
cd - && git worktree remove ../verify-eu

A new test for the behaviour you added must fail without the implementation; guard tests for what must not change (criteria 2–4 here) are expected to pass on main as well. Protecting the test oracle covers the other ways agents weaken tests. Push the branch, open the pull request and let CI and your review agent, such as Bugbot, run on it. You sign off on the evidence: criteria mapped to named tests, a clean scope check and green CI. The evidence bundle page turns that into a pull request template.

Merge parallel branches in a safe order

Merge the branch with the smallest scope and the strongest tests first. Every merge changes main, so every remaining branch is now tested against a base that no longer exists.

1. Merge the first ready branch through its pull request, with CI green.
2. Rebase each remaining agent branch on the new main, or ask its agent to do it: “Rebase this branch on main, rerun the proof command and print the status block.”
3. Run the scope and overlap checks again. A rebase can surface conflicts the agent resolved in a way you did not intend.
4. Repeat until the queue is empty. Delete merged worktrees with git worktree remove <path> and prune branches, so the next fan-out starts clean.

When should you coordinate one run instead of starting separate agents?

Use a coordinated run when the work is one outcome that needs several steps or several repositories, such as a feature from API to UI or a framework migration. Separate agents suit separate outcomes. The difference is who splits the work: with separate agents you write each card; in a coordinated run, a plan splits one outcome into child tasks. We could not verify a Cursor feature named Projects that does this for you (as of 2 October 2026), so this page describes the run you coordinate yourself, with Plan Mode and the Agents Window.

Handing the split to an agent moves your job, it does not remove it. You now verify two things: that the plan covers the outcome, and that each child pull request carries its evidence. If your build offers any feature that splits work for you, confirm three things in Cursor’s documentation before you trust it: where child tasks run, whether you can approve the plan before work starts, and what it does with a child that fails. Then write the outcome as a brief with a test the whole run must pass.

Copy-paste prompt: a project brief for a coordinator

PROJECT BRIEF: Replace moment.js with date-fns across the web app and the API.

Outcome: no import of moment remains in apps/web or apps/api, and every date shown to users is unchanged.
Repositories and paths in scope: apps/web/src/**, apps/api/src/**, packages/date-utils/**
Out of scope: database migrations, CI config, anything under infra/.

Acceptance test for the whole project (run it after every merged child):
1. `grep -rE --exclude-dir=node_modules "(from|import|require\(|import\()[[:space:]]*['\"]moment([/-][^'\"]*)?['\"]" apps/ packages/` prints nothing (this also catches `import 'moment'`, `moment/locale/*` and `moment-timezone`).
2. `grep -rE --include=package.json --exclude-dir=node_modules '"moment(-[a-z]+)?"[[:space:]]*:' apps/ packages/ package.json` prints nothing, so no package.json lists moment or moment-timezone as a dependency.
3. `npm test` passes in apps/web and apps/api.
4. The snapshot suite `npm run test:dates` shows zero changed snapshots.

How to split the work:
- First, a plan: list child tasks, each with its own allowed paths, acceptance criteria and proof command. No two child tasks may share a file. Show me the plan and wait for my approval before starting any child.
- Start packages/date-utils first; web and api tasks depend on it.
- Each child opens its own pull request with the status block: STATUS, BLOCKED_ON, CRITERIA, PROOF (final 10 lines), FILES, OUTSIDE_SCOPE, NEXT.
- Report after each merged child: the acceptance test output and which child tasks remain.

The approval gate before the first child is the part that saves you. A plan with two children editing the same file is cheap to fix before it runs and expensive after.

Run the brief in Plan Mode, approve the plan, and start each child task card as its own agent from the Agents Window. The coordinator then is you, and the acceptance test stays the same. For work that spans separate repositories, multi-repository workflows in Cursor covers contracts between them.

What breaks when you run several Cursor agents at once?

An agent sits blocked on a question for an hour. Parallel agents fail silently when you stop looking. Recovery: triage on the fixed rhythm from step 5, and put the answer to common questions (which test command, which fixture) into the task card or into project rules so the next agent does not ask.

Two agents edit the same shared helper. The overlap check prints the file on two branches. Recovery: merge the branch that owns the helper, rebase the other, and tighten both cards’ allowed paths. Next time, give the shared change to one agent first and fan out after it merges.

The worktree cannot build. Missing dependencies, a missing .env.local or a port already taken by your main checkout. Recovery: fix scripts/agent-setup.sh once, in the repository, rather than patching each worktree by hand. Give each worktree its own port and database name.

The agent reports READY, and a test was changed to pass. Recovery: run the scope check against tests/ separately and look at every changed assertion; add “Do not edit, skip or weaken an existing test” to the card if it was missing. Reject the branch rather than repairing it in place.

Best-of-N attempts all look plausible. Three passing diffs are three things to compare. Recovery: pick by evidence, not by reading. Keep the attempt whose tests are strongest (the tests for new behaviour fail without the implementation) and whose diff is smallest, and delete the rest before they drift.

Spend climbs faster than merged work. Each agent consumes model usage while it runs, and a stuck agent consumes it without progress. Recovery: stop any agent that reports STUCK twice, rewrite its card, and cap the number of running agents at the number whose branches you can verify in a day. Token management in Cursor covers usage limits.

A cloud agent gets a secret it should not have. Recovery: give cloud environments only test credentials scoped to a sandbox, rotate anything that reached one by mistake, and review permissions and sandboxing for agents.

How Claude Code and Codex run parallel agents

This page stays on Cursor. The same workflow (isolated checkout, task card, status block, scope check, merge order) carries over unchanged to the other tools. Claude Code has agent view (claude agents, research preview in v2.1.283) and --worktree; see Agent view in Claude Code. Codex has codex agents to browse agent sessions and --worktree for a managed Git worktree (codex-cli 0.157.1); see multi-agent workflows in Codex.

Where to go next with parallel agents in Cursor

Checkpoints and branching Undo, micro-branches and worktrees for a single agent.

Cloud agents and Automations Run agents on cloud machines, on a schedule or on events.

Orchestration patterns Fan-out, pipelines and coordinators across tools.

Reading evidence instead of code How to sign off on agent work without reading every diff.