Flavor one - local fan-out across parallel worktrees

This chapter walks three flavors of more-than-one-agent work - this page is the first: local fan-out, then delegated subagents, then cloud agents. Cursor’s local fan-out takes a single prompt and runs it across several agents at once, each in its own isolated copy of the codebase. It shipped in Cursor 2.0 as the multi-agent sidebar; today this work lives in the Agents Window, Cursor’s agent-first workspace for running agents across local and cloud environments, with worktrees as its mechanism for isolated local parallel work (as of September 2026 - Agents Window reference). On fleet size, the 2.0 changelog that introduced the feature is still the only place a number appears: “Run up to eight agents in parallel on a single prompt” (2.0 changelog). Later releases neither restate nor rescind a cap, so read eight as the last documented figure, not a guarantee about today’s interface.

How you actually dispatch one is this: open the Agents Window (the reference documents the editor route - the command palette’s “Open Agents Window” - and covers its capabilities), and start more than one agent there - the docs describe worktrees as the mechanism (“run agents in isolated Git checkouts so each task has its own files and changes”), with each agent you start getting its own checkout. The current docs do not walk the one-prompt-to-many gesture step by step, so treat the linked reference as the source for the exact controls rather than any tutorial’s screenshots.

There are two distinct ways to use it, and this page exercises both with the course’s illustrative budgetcli scenario - a small self-hosted personal-finance API: the caching decision you can’t make from reading alone, and the float-to-cents migration that has to touch many files without the workers colliding.

Competing agents - same prompt, compare the results. Point the same prompt at several agents and let each take its own swing. This is the caching decision: you write the brief once, fan it out, and get back several complete implementations to compare side by side instead of one you have to trust blind. An illustrative brief:

> Add a caching layer to the reports endpoint in src/api/reports.ts.
  Keep the public response identical; add cache invalidation on any
  write that touches a report's underlying rows. Make it production-shaped,
  not a sketch.

Dispatched across three agents, you get three real branches to read - one that reached for in-process LRU, one for Redis, one for a materialized view - each having actually written the code, run against your real types, and produced a diff you can review. You’re no longer guessing which approach is cleanest; you’re reading three answers and keeping the best.

Cooperating agents - different slices, no shared working tree. Point each agent at a different slice of the same job. This is the float-to-cents migration: agent one takes the parsing layer, agent two the storage layer, agent three the report formatting, all running at once. They’re not competing - they’re dividing labor - and the reason they don’t corrupt each other is the isolation mechanism underneath.

Why each agent gets its own worktree

When several agents edit one working directory at once, the failure isn’t merge conflicts - it’s worse, and it’s the reason isolation is load-bearing rather than a nicety. Picture two agents in one directory. Agent A is halfway through rewriting src/lib/money.ts, the file saved in an inconsistent state mid-edit. Agent B, working a path that imports it, reads that file right now and reasons over a half-written version that never existed in any commit and never will. The result is a non-deterministic failure even though the two slices were logically independent. Agents make this worse than humans do - they don’t pause to notice something looks off, they auto-iterate on the bad state, and they can’t attribute a passing test to the right branch.

A git worktree fixes exactly this. One repository, but multiple checked-out working directories - each with its own branch, its own index, its own files on disk - all sharing the same underlying object database and history. That buys file-level isolation (B can’t see A’s unsaved edits), index isolation (each has its own staging area), and a branch lock (git refuses to check out a branch that’s already checked out elsewhere). Cursor’s fan-out does this for you: per the 2.0 changelog, it “uses git worktrees or remote machines to prevent file conflicts,” so each agent operates in its own isolated copy of the codebase (2.0 changelog). The cooperating agents on the cents migration never read each other’s half-written files, and the competing agents on the caching decision never clobber each other’s branch.

The isolation a worktree gives you is code state - files, index, branch pointer. It does nothing for execution state, and that gap bites the cents migration the moment a worker tries to run the test server. Three agents in three worktrees still share ports and the dev database - so two of them binding localhost:8000 or running concurrent migrations against one shared dev database will collide outside any worktree’s protection. A root .env is the opposite problem: it lives inside the working directory but is usually untracked, so fresh worktrees do not get it at all and their workers fail to boot until you copy the config each one needs. The rule of thumb splits accordingly: anything that lives outside the working directory is not isolated (a per-worker port range, a per-worktree database file), and untracked files inside it do not travel (copy them in). And one line worth its own sentence - runtime isolation is not security isolation. A worktree keeps honest, cooperating agents from tripping over each other; it does nothing against untrusted code or prompt injection. For that, the guardrails are the sandbox and permission defaults from the permissions chapter, layered underneath.

Reviewing and merging the competing results

Fan-out’s real work happens at the end, not the start - and skipping it is how you turn a slate of options into a faster way to ship the wrong one. Each agent comes back with a branch and a diff. For the competing caching agents, you read all three against one question you decided up front - which keeps the response identical with the least new surface area? - and you keep one. The Redis branch might be cleanest in isolation but drag in an infrastructure dependency you don’t want; the materialized-view branch might be the least code but the hardest to invalidate correctly. You’re making an engineering call across three real implementations, which is exactly the call you couldn’t make from reading the endpoint alone. The other two branches get thrown away - that’s not waste, that’s the point. You paid compute to buy a comparison - a cost decision, spending machine time to replace the more expensive rework of shipping the wrong design.

For the cooperating cents agents, the merge is a different shape: you’re not picking a winner, you’re integrating three slices that should compose. Review each branch on its own terms - does the parsing slice actually convert at every entry point, does the storage slice round-trip cleanly - then merge them in sequence, running the test suite after each so a silent failure in one slice can’t hide behind a green run from another. And the review discipline does not soften as the fan-out widens - it hardens: what comes back is a proposal you review, never a result you apply. More agents means more surface for a confident-but-wrong diff, so the review gate gets more important as you widen the fan-out, not less.

So the shape that works for flavor one: fan out when the task has competing approaches you want compared or independent slices you want done at once; let the worktree isolation keep the agents from corrupting each other; namespace anything that lives outside the working tree yourself; and treat the returning branches as a slate to review, never a result to merge blind.

Try it

Create a git worktree for a branch (git worktree add -b experiment ../budgetcli-experiment). Open both in separate Cursor windows. Make independent changes in each. Merge the experiment branch back and resolve any conflicts.

That is the widest radius Cursor gives you on your own machine: a fleet, one prompt, and a slate of branches at the end. The next flavor narrows it hard - instead of several agents taking the same brief, a single worker you defined in advance takes one scoped job and hands back only what it concluded. Next: delegated Subagents.