The problem: the agent starts before it has understood, and two agents step on each other
You asked the agent to add Google sign-in. Twenty minutes later you have code that works, but it touched a middleware it should have left alone and added a dependency you did not want. The flaw is not in the code: the agent started writing before it had understood what you were asking. And if you try to fix that by launching three agents together, a second problem appears: if two of them edit the same file in the same folder, one overwrites the other's work.
This article covers the two remedies Cursor offers, which combine well. Plan Mode puts a plan for you to review between your request and the first modified file. Parallel work, which in the early versions was called Background Agents, now comes in three different forms (local worktrees, cloud agents and subagents), and it pays to tell them apart because their costs and risks are very different. They come after Agent mode and the project rules: I take both as known.
A word on method, because in this series it matters. Cursor was not installed where I wrote this: everything about buttons, menus and the agent's behavior comes from the official documentation I read on 2026-11-13 and is declared "not tried here". What can be run without the editor, namely git, the configuration files and a plan-checking script, I really ran, and I report the real output.
What changed compared with the previous version of this article
The text that used to be here described a feature called "Mission Control", a cap of "eight agents" running in
parallel, shortcuts such as Cmd+Shift+N and a setting called git.showCursorWorktrees. In
the documentation and the changelog I opened today I found none of these things, so they are gone.
The names have changed too: the Cloud Agents page reports, in its "Naming History" section, that they were "formerly
called Background Agents". And the picture is wider: the agents window (Agents Window) is available
with Cursor 3, released on 2 April 2026 according to the documentation. If you read guides that use the old
names, check that they still describe the product.
Plan Mode: have it write a plan before the code
You turn it on with Shift+Tab from the chat input field, which cycles through the modes; Cursor can also suggest it on its own when it recognizes keywords of a complex task. The documentation describes the flow in five steps, and here the order really matters: the plan comes after the questions and the reading of the code, and execution only after your review.
- The agent asks you questions to clarify the requirements.
- It explores the code to gather the relevant context.
- It produces a detailed implementation plan.
- You review and edit it, in chat or directly in the Markdown files.
- When you are ready, you start building the plan.
The step that makes the difference is the fourth. A plan is text you can correct in thirty seconds, while a design mistake discovered after execution costs an intervention across many files. That is why the documentation gives a counterintuitive piece of advice: if the agent built something different from what you wanted, do not chase it with follow-up prompts. Undo the changes, make the plan more precise and run it again. Redoing from the plan is often faster than repairing a run that has already gone astray, and it gives a cleaner result.
Where the plan ends up, and why it is worth saving in the repository
By default plans are saved in the user's home folder, so outside the project. The "Save to workspace" button moves them into the workspace, and the documentation gives three reasons: future reference, sharing with the team, documentation. The default has a consequence nobody points out to you: a plan that is not saved in the workspace does not end up in the commit, and the colleague who has to review your pull request does not know what you agreed with the agent. If the plan is a project decision, save it and put it under version control.
What a plan looks like, and what to check
The documentation does not fix a format for the plan: it is free-form Markdown, and the structure depends on the model and on your request. The block below is therefore an example I built myself, not Cursor's output. It serves to show where a plan most easily goes wrong: it cites files by their path, and those paths may be invented.
# Plan: OAuth2 with Google
## Analysis
- The service is in `src/auth/auth.service.ts`, the guard in `src/auth/auth.guard.ts`.
- The JWT is handled in `src/middleware/jwt.middleware.ts`.
## Steps
1. Add the dependency in `package.json`.
2. Create `src/auth/strategies/google.strategy.ts` (new file, does not exist yet).
In this test plan the service and the guard exist, while the JWT middleware is a path the agent assumed, and the last file is declared new. Checking some twenty paths by eye is tedious, and tedium is exactly the moment when you approve without reading. Better to delegate the mechanical part to a script.
"""Check that the paths cited in a plan really exist in the repository."""
import re
import sys
from pathlib import Path
EXTENSIONS = r"(?:ts|tsx|js|json|md|mdc|py|java|html|css|sql|yml|yaml)"
# a path = at least one slash and a known extension, inside backticks
PATTERN = re.compile(r"`([\w@./-]+/[\w@.-]+\." + EXTENSIONS + r")`")
def cited_paths(text: str) -> list[str]:
seen: list[str] = []
for m in PATTERN.finditer(text):
p = m.group(1)
if p not in seen:
seen.append(p)
return seen
def main(plan: Path, root: Path) -> int:
missing = []
for p in cited_paths(plan.read_text(encoding="utf-8")):
exists = (root / p).exists()
print(("ok " if exists else "MISSING ") + p)
if not exists:
missing.append(p)
return 1 if missing else 0
if __name__ == "__main__":
sys.exit(main(Path(sys.argv[1]), Path(sys.argv[2])))
The script looks, inside backticks, for every string that contains a slash and ends with a known extension, and
checks that the file exists starting from the repository root. The list of extensions is in the constant
EXTENSIONS: if your project uses .vue or .go, add them, because paths
with other extensions are not seen. The exit code is 1 if at least one file is missing, so you can put it in
a check script. I ran it on a test repository that contains only the three real files
(python3 -I check_plan.py plan.md repo, Python 3.14, two runs with identical output):
ok src/auth/auth.service.ts
ok src/auth/auth.guard.ts
MISSING src/middleware/jwt.middleware.ts
MISSING src/auth/strategies/google.strategy.ts
The check flags two missing paths, but one of the two is a false alarm: the file
google.strategy.ts is declared new, and the plan says so. The real problem is the JWT middleware,
which the agent cited although it does not exist. The script cannot tell the two cases apart, and it is not meant to: its job is to
send you to read exactly that line. It does not prove that the rest of the plan is right, because an
existing path can still be the wrong file to modify.
When Plan Mode is not needed
The documentation recommends it for four situations: complex features with several valid approaches, tasks that touch many files or systems, unclear requirements to explore, architectural decisions to review beforehand. For a small change or a task you have already done many times, going straight to Agent mode is fine. A practical rule I draw from it: if you can already say in one sentence which files will change, the plan gives you nothing; if you cannot, the plan is the cheapest way to find out.
Three ways of working in parallel, which must not be confused
The phrase "background agent" now covers different things. There are three routes, and the first question to ask is where the work runs and where the files end up.
- Local worktree: the agent works on your computer, but in a separate copy of the repository with its own branch.
- Cloud Agent: the agent works on an isolated virtual machine in the cloud, clones the repository, works on a branch and hands the changes back to you.
- Subagent: a specialized assistant with its own context window, launched by the main agent, in the foreground or in the background.
The dividing line is isolation, and each one offers a different kind. The worktree isolates the files and uses your resources and your network. The Cloud Agent also isolates the machine, but you have to entrust it with the repository and secrets. The subagent isolates only the context, that is the memory of the conversation, and works on the same files as the agent that launched it: it does not protect you from conflicts. Whoever launches "three agents in parallel" thinking they are all the same thing gets surprises on one of these three levels.
Worktrees: the technology is git, and you can try it without Cursor
A git worktree is a second working folder linked to the same repository, with its own active branch. It is
not a clone: it is associated with the same repository, with metadata of its own, and the git documentation
specifies that the references in refs/ are shared while HEAD belongs to each worktree. Cursor uses it to give each agent a folder of its own. The documentation specifies where: the worktree
interface is available in the Agents Window, while in the editor you use the commands /worktree (to
run an entire chat in a separate checkout) and /best-of-n, which launches the same task on several
models, each in its own worktree, without merging the results: you choose the winner and bring it into your
checkout with /apply-worktree.
The delicate point is that parallelism does not eliminate conflicts: it moves them to the moment the branches are merged. The
following script shows it with plain git. It creates a temporary repository with two worktrees, has two
"agents" add a route in the same place of the same file, and then merges the branches. It opens no ports and does not write into
your repository: it works in a folder created with mktemp -d that it deletes at the end.
#!/usr/bin/env bash
set -euo pipefail
base=$(mktemp -d)
cd "$base"
git init -q -b main project && cd project
git config user.email test@example.com && git config user.name Test
mkdir src
printf 'export const routes = [\n "home",\n];\n' > src/routes.ts
printf 'export const title = "App";\n' > src/title.ts
git add . && git commit -q -m "base"
git worktree add -q ../agent-a -b feature/a
git worktree add -q ../agent-b -b feature/b
echo "== active worktrees (hash removed)"
git worktree list | awk '{print $1, $NF}' | sed "s#$base#<tmp>#"
# agent A adds a route and touches a file of its own
( cd ../agent-a && sed -i 's/ "home",/ "home",\n "login",/' src/routes.ts && git commit -qam "a: login" )
# agent B adds another route in the same spot
( cd ../agent-b && sed -i 's/ "home",/ "home",\n "profile",/' src/routes.ts && printf 'export const title = "App B";\n' > src/title.ts && git commit -qam "b: profile" )
echo "== merge of A (clean)"
git merge -q --no-edit feature/a && echo ok
echo "== merge of B (same file)"
git merge --no-edit feature/b 2>&1 | sed 's/^/ /' || true
echo "== conflicting file"
git diff --name-only --diff-filter=U
echo "== the file src/routes.ts"
cat src/routes.ts
git merge --abort
cd / && rm -rf "$base"
I ran it with git 2.53.0 twice, with identical output (run with LC_ALL=C, so that git prints its messages in English; hashes
do not appear because I removed them from the listing):
== active worktrees (hash removed)
<tmp>/project [main]
<tmp>/agent-a [feature/a]
<tmp>/agent-b [feature/b]
== merge of A (clean)
ok
== merge of B (same file)
Auto-merging src/routes.ts
CONFLICT (content): Merge conflict in src/routes.ts
Automatic merge failed; fix conflicts and then commit the result.
== conflicting file
src/routes.ts
== the file src/routes.ts
export const routes = [
"home",
<<<<<<< HEAD
"login",
=======
"profile",
>>>>>>> feature/b
];
Read the output in order. The first branch merges without problems, the second fails because both have
modified the same line of src/routes.ts. Git left the markers
<<<<<<< and >>>>>>> in the file and the choice between the two versions is
yours. This is the most common case, and it is the reason why, before launching parallel agents, you should look at the
plan and ask which files they will touch: a "central" file, such as a list of routes or an index, is where
conflicts are born. The script also has a limit: it simulates the agents with two sed commands, and it
says nothing about how a real agent behaves when facing a conflict.
Preparing the worktree: .cursor/worktrees.json
A new worktree has only the files tracked by git: node_modules and the environment files are missing. Cursor
reads a file .cursor/worktrees.json (first in the worktree's path, then in the project root)
with commands to run after creation. There are three keys: setup-worktree-unix for macOS and Linux,
setup-worktree-windows, and setup-worktree as a fallback for all systems. Each accepts an
array of shell commands, run in sequence inside the worktree, or the path of a script relative to the file. On
Unix the specific key takes precedence over the fallback.
{
"setup-worktree-unix": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env"
],
"setup-worktree": [
"npm ci"
]
}
The file is valid JSON (I loaded it with Python), but its effect inside Cursor was not tried here. The variable
ROOT_WORKTREE_PATH appears in the documentation's examples as the path of the main checkout,
from which to copy the .env. Two cautions: the documentation advises against linking the
dependencies with a symbolic link, because it can cause problems in the main worktree, and suggests a fast package manager such as
pnpm. And a cp of the .env moves your secrets into another folder: that is fine on your own
computer, but remember it if that folder is later copied or synchronized elsewhere. To understand why a setup
fails, open the Output panel and choose "Worktrees Setup".
Automatic worktree cleanup, and what it can delete
Worktrees take up disk space, and Cursor keeps a maximum number of them: the documentation indicates, starting from Cursor 3.5,
two machine-level settings, cursor.worktreeMaxCount (a cap of 25 worktrees per computer, summed
across all projects) and cursor.worktreeCleanupIntervalHours (how many hours between checks; the page's
example uses 6). When the cap is exceeded, the oldest are removed. The detail not to miss is on the same
page: the cleanup rediscovers all worktrees, including those created outside the manager with git worktree add,
and treats them as deletable. If you have uncommitted work in a worktree, do not rely on the fact that "I created it
by hand": commit it or move it.
Cloud Agent: another machine, with other risks
A Cloud Agent uses the same principles as the local agent but runs in an isolated virtual machine, with a full development environment: cloned repositories, dependencies, secrets, startup commands and network access. It can build and try the software, and produce artifacts (screenshots, videos, logs) attached to the pull request. The declared advantage is that your computer does not need to be on and connected, and that you can start as many as you like in parallel. The price of this advantage lies in three points, which the documentation states and which are worth lining up before adopting it.
- You need a plan that includes them: Premium and above, Teams, Enterprise or an earlier paid plan; Free and Plus do not.
- An account administrator must connect the code provider (GitHub, GitLab, Bitbucket Cloud or Azure DevOps), and you must have read and write permissions on the repository.
- Consumption adds to your plan usage, at the price of the model you choose, and the first time you use it you are asked for a spend limit.
I do not report price figures: they change, and the pricing page should be read on the day you decide. The signal I draw from it is a different one: the cost of a cloud agent is proportional to time and model, so the spend limit is not a formality. Launch the first agent on a small task and watch the consumption before launching five.
The environment matters more than the prompt
The documentation insists on a point that overturns the way you think about it: an agent that writes code but cannot run
the tests or reach the services does not close the loop of its work. The environment is configured with a
procedure guided by the agent, with a saved snapshot or with a Dockerfile indicated in .cursor/environment.json. Here I did not
try any of the three: I refer you to the setup page for the exact fields. A reasonable test task is
to run the existing tests, because if the agent cannot do that, the environment is almost certainly incomplete.
Secrets, MCP and hooks in the cloud: what the agent sees
Here the risk becomes concrete. Secrets are entered in the dashboard panel and injected when the
agent starts: an agent that is already running does not see secrets added afterwards. For MCP servers the transport changes
what the agent can read. With HTTP, recommended by the documentation, the configuration is never present on the
virtual machine and calls go through Cursor's backend; with stdio the server runs inside the machine, so
the agent can access its configuration and its environment variables. If a server requires a
powerful key, using stdio in the cloud means handing it to the agent. SSE and mcp-remote, according to the same
page, are not supported for custom servers.
Hooks, the subject of the next article, work
in the cloud too: agents run the command-based hooks defined in the repository's .cursor/hooks.json,
while those in your ~/.cursor/hooks.json are not available, because the virtual
machine does not see your home folder. A check that lives only in your personal configuration, therefore,
does not protect the work that runs in the cloud: if it is a project rule, it must be in the repository.
Where they are started
The documentation lists many entry points: the "Cloud" selector in the desktop app, the web interface and
the iPhone app, the @cursor command in Slack, in a GitHub or Bitbucket comment and in Linear, plus
the API. In the Agents Window there are also /in-cloud, to hand a task to a cloud subagent, and
/autopilot for a pull request. The convenience of typing @cursor in a comment makes it easy to launch work without anyone keeping an eye on the cost.
Decide who may do it.
Subagents: separate context, not separate files
A subagent has a context window of its own, receives from the main agent a prompt with the necessary information
(it does not see the previous conversation) and returns a final message. It can run in the foreground, and then
it blocks the main agent until it has finished, or in the background, and then it returns immediately and works on its own. Cursor
includes two by default, Explore (searches and analyzes the code, with a faster model) and
Browser (controls the browser through MCP), designed for operations that produce a lot of intermediate
output and risk filling the main context. You can define your own as Markdown files with a
YAML header in .cursor/agents/ (for the project) or in ~/.cursor/agents/ (for you), and
the documentation says that, for the same name, the .cursor/ folder wins over .claude/ and .codex/.
The golden rule is in the comparison table on the same page: a single-action task, such as formatting or generating a changelog, is a skill, not a subagent. The subagent is for when the context is too large or the threads are truly independent. And remember that it shares files with its parent: if two subagents modify the same file, the conflict is in the same folder and you do not see it as a git marker but as an overwrite.
A method for deciding, on a concrete example
Imagine an Angular application of which you are the only maintainer and three tasks: fix the validation of a form, add a filter to a table, update a library with breaking changes in three modules. It is a scenario built for this article, with no real data. The first task is small and you do it in Agent mode. The second touches a single component: a local worktree is enough, and you can keep working in your checkout. The third is the case where the plan pays off: you have it written in Plan Mode, check with the script that the cited files exist, save it in the workspace and then decide whether to give one module to each agent. If the three modules share a configuration file, that file is modified first and by hand, and only afterwards do you parallelize. Your attention shifts from typing to deciding in which order and within which boundary to make the agents work.
What you can do now
You know when to use Plan Mode and when to skip it, you know that the plan should be saved in the repository if it is a decision and checked for paths before being approved, and you can tell apart three forms of parallelism that have different isolations. You have seen with git, reproducibly, why two agents on the same file produce a conflict, and you know that a Cloud Agent requires a paid plan, a configured environment, a spend limit and a conscious choice about secrets and MCP transport. What you do not have yet is a way to stop a dangerous action before it happens: that is the subject of hooks, in the next article.
Frequently asked questions
How do you turn on Plan Mode in Cursor?
By pressing Shift+Tab from the chat input field, which cycles through the modes, or from the mode selector. Cursor can also suggest it when it detects keywords of a complex task. Where the plan is stored and how to save it is explained in the Plan Mode documentation.
Do Background Agents still exist?
The name has changed: the documentation calls them Cloud Agents and in the "Naming History" section says they used to be called Background Agents. They run on a virtual machine in the cloud, and they need a plan that includes them and a spend limit.
Can two agents in parallel modify the same file?
With two separate worktrees yes, but the conflict shows up when you merge the branches, as the git test in this article shows. With two subagents in the same folder no: they share the files and one can overwrite the other. That is why it pays to check beforehand which files they will touch.
Do the hooks on my computer also apply to cloud agents?
No: the hooks in ~/.cursor/hooks.json are not available in the cloud, because the virtual machine does not see your home folder. Those in the repository's .cursor/hooks.json apply and, on Enterprise plans, so do the team and enterprise ones.
The same series also includes Cursor IDE: The Complete Developer Guide.
Sources
- Cursor documentation: Plan Mode - the five-step flow, activation with Shift+Tab, saving plans, restarting from the plan, accessed on 2026-11-13
- Cursor documentation: Cloud Agents - virtual machines, plan requirements, starting points, MCP and hook support, previous name Background Agents, accessed on 2026-11-13
- Cursor documentation: Cloud Agent capabilities - HTTP and stdio MCP transports, redacted secrets, artifacts, accessed on 2026-11-13
- Cursor documentation: Worktrees -
.cursor/worktrees.json,/worktree,/best-of-n, automatic cleanup, accessed on 2026-11-13 - Cursor documentation: Agents Window - availability with Cursor 3 of 2 April 2026,
/in-cloudand/autopilot, accessed on 2026-11-13 - Cursor documentation: Subagents - separate context, foreground and background modes, default subagents, subagent folders, accessed on 2026-11-13
- Git documentation: git-worktree - main and linked worktrees, shared references and per-worktree HEAD, accessed on 2026-11-13
The wt.sh script was run with git 2.53.0 and check_plan.py with Python 3.14, each twice with identical output, in temporary folders outside the repository. The worktrees.json file was loaded as JSON but not tried in Cursor, which was not installed: like every step inside the editor, it is a scheme to adapt.

Commenti
Caricamento commenti...
Sign in to comment