Cursor's Agents Window, CLI and cloud agents: which to use when

Last checked: 21 Oct 2026. The facts below come from Cursor's documentation, help centre, changelog, blog, pricing page and its public Cursor Learn course, with the US National Vulnerability Database, DORA and the Cloud Security Alliance for the points that sit outside Cursor, all read on that date and linked where they are used.

Cursor runs one agent behind four ways of working: the Agents Window, the editor, the command line and cloud agents. Choose by where the work runs and who is watching it. Supervised, hands-on work belongs in the Agents Window or the editor, scripted and pipeline work belongs in the CLI, and well-specified work that should carry on without a laptop belongs in cloud agents, once their environment is set up.

Cursor's documentation compares its surfaces two at a time, so the table and rules below are our synthesis, each point linked to the Cursor page it rests on. We use Cursor in our own engineering, and this is the guide we would give a lead writing down how the team works.

One agent, four surfaces

Every surface runs the same kind of agent. Cursor's agent overview says an agent is built on instructions, tools and the model you pick, which the Working with agents chapter of Cursor Learn calls the "harness". What changes between surfaces is where the agent runs, how much it asks before acting and how you supervise it.

The newest surface is the Agents Window, which Cursor says became generally available with Cursor 3 on 2 Apr 2026. Cursor describes it as its "agent-first interface", and its Cursor 3 announcement says all local and cloud agents appear in its sidebar, including those started from mobile, web, Slack, GitHub and Linear. You open it from the command palette with "Open Agents Window", and "Open IDE" takes you back to the classic editor on the same workspace. You can also keep both open.

Cloud agents were formerly called Background Agents, in case older team notes use that name.

How to choose a surface for a job

Cursor's own rule covers the first choice. Its Agents Window page says the window "works well when you want to run and manage many agents in parallel", and that the editor "works well when you want the classic IDE with VS Code extensions and flexible screen splitting to see many files at once". Cursor says it will keep supporting both, so this is a choice per task.

The rest of the decision, in our view, comes down to four questions:

• Is a person supervising each step? Exploratory work, debugging and anything review-heavy belongs in the Agents Window or the editor, where the developer sees each change as it happens.
• Should the work run without a person at all? Scheduled scripts and CI jobs belong in the CLI's print mode, inside your own pipeline, where Cursor's GitHub Actions guidance applies.
• Is the task well specified and able to wait? Cloud agents suit work you would otherwise add to a to-do list. Cursor Learn's reviewing and testing chapter names bug fixes, test coverage, documentation updates and refactors. They only pay off once the environment is set up, covered below.
• Do several tasks need the same repository at once? Use worktrees locally or send the work to the cloud.

Parallel agents have a cost. Cursor Learn notes: "If your tests take 10 minutes to run and you launch 10 agents in parallel, that's nearly two hours of waiting." DORA's 2025 research calls AI "an amplifier, magnifying an organization's existing strengths and weaknesses". Our reading is that more agents move the bottleneck to review capacity and test environments, so fix those first.

Running several local agents with worktrees

Two agents editing one checkout can trip over each other's changes. Cursor's worktrees page says worktrees "let Agent work in isolated Git checkouts", and to use them "when you want to start several agents on the same repo without conflicts". They are opt-in for each agent, and each surface has its own route:

• Agents Window: you start an agent in a worktree or move an agent into one, and Cursor creates a separate checkout. Cursor says this point-and-click feature is only available in the Agents Window.
• Editor: /worktree runs a task in an isolated checkout, /apply-worktree brings the changes into your main checkout and /delete-worktree removes the checkout. /best-of-n runs the same task across several models, each in its own worktree, and Cursor notes it "compares runs only" and merges nothing back.
• CLI: the CLI guide says passing -w or --worktree runs the agent in a new Git worktree, stored alongside worktrees created from the editor.

Each worktree is a fresh checkout that needs its own dependencies. A .cursor/worktrees.json file holds setup commands, and Cursor checks it whenever a worktree is created on any of the three local surfaces. Cursor recommends against symlinking dependencies into the worktree and suggests a fast package manager such as bun, pnpm or uv. In the CLI, the changelog says these setup commands now run only after the workspace is trusted.

Two limits are worth telling the team. Cursor's default cap is 25 worktrees per machine, and its cleanup pass treats worktrees created outside its manager, including plain git worktree add ones, as eligible for deletion, so push or apply work you want to keep. The second is our reasoning from Git's own description: a worktree separates files and branch state but not a local database, running services or ports, so two agents testing against the same local database can still interfere.

Using the Cursor CLI in scripts and CI

The Cursor CLI supports the same Agent, Plan and Ask modes as the editor and reads the same rules and mcp.json configuration. It also reads AGENTS.md and CLAUDE.md at the project root, so one AGENTS.md can serve developers on more than one tool. Interactively, it asks you to approve or reject terminal commands unless permission rules pre-approve or deny them, and agent resume or agent ls reopens earlier sessions.

For scripts and pipelines, print mode (-p or --print) runs the agent non-interactively. The parameters reference lists three output formats: text (the default), json and stream-json. The JSON format returns one object, including the result and an error flag, for a pipeline step to parse.

Four points decide whether CI use is safe:

1. Credentials. In CI the CLI authenticates with a user API key generated in the Cursor dashboard and held as a repository or organisation secret. Our reading is that, on a plan without service accounts, that key is tied to one person's account and usage. Service accounts exist for non-human credentials, but only on the Enterprise plan.
2. How much autonomy the agent gets. Full autonomy gives the agent control of git, API calls and external interactions, which Cursor says "requires more trust". Restricted autonomy lets the agent change files while separate workflow steps handle the branch, commit, push and comment. Cursor recommends the restricted pattern with permission-based restrictions for production CI, so that "critical operations remain deterministic and auditable".
3. The permissions file. Permissions sit in ~/.cursor/cli-config.json globally or .cursor/cli.json per project, and Cursor's permissions reference says "Deny rules take precedence over allow rules". Cursor's CI example denies the git and gh commands and writes to .env files and package.json. Note that --force (alias --yolo) allows commands unless explicitly denied.
4. Whether print mode writes files by default. Cursor's pages disagree. Three say print mode has write and shell access, while an example on the headless page says changes are only proposed without --force. Test it on a scratch repository before relying on either behaviour, and set explicit deny rules regardless.

Two more checks. Cursor's changelog says admins can disable headless mode with a team setting, so confirm it is allowed before building a pipeline around it. And the Cloud Security Alliance's research note on AI agents in GitHub Actions makes the same point from outside Cursor: an agent that reviews code for security issues "does not need the ability to push commits".

What cloud agents need before a team relies on them

Cursor's cloud agent documentation says they "run in isolated VMs in the cloud with full development environments", and that you can run as many as you want in parallel without your machine being connected. They work on a separate branch and push changes back for handoff. You can start them from the Agents Window, cursor.com/agents, the iOS app, Slack, GitHub, Linear or the API.

Four things have to be in place first:

• Source control. Cursor says a Cursor account admin must connect source control before anyone can start a cloud agent from a repository.
• An environment. Cursor calls environment setup "the most important step to improve the effectiveness of cloud agents". The routes are agent-led setup or a committed configuration (a snapshot or a Dockerfile referenced from .cursor/environment.json). The setup page notes that a saved environment reads that file only when its location setting points to it, and builds keep the last working environment if a new one fails.
• A repository that runs locally. Cursor's best practices say: "If it is hard for a human developer to test locally, it will also be hard for an agent."
• A plan that includes them. Cursor's pricing page lists cloud agents and automations from Premium upward, with legacy paid plans following their own rules. Check your plan there.

Then the risk model changes. Cursor's security page says cloud agents "auto-run terminal commands so they can iterate on tests without stopping for approval on every step", names the prompt-injection risk of code being sent to an external host, and says internet access is on by default but can be restricted to allowlisted domains. Work comes back as a draft pull request for a person to review. If an admin enables team follow-ups, Cursor warns that one person can influence an agent running with another person's credentials. Cursor's data governance page says cloud agents are "the only feature that requires Cursor to store code", and that data residency today is a US-only programme, with EU and UK coverage for inference only, on request.

We cover the security settings in Cursor cloud agent security and what to hand to cloud agents and automations first in Cursor cloud agents and automations.

Moving a task between local and cloud

The Agents Window moves agents both ways. Cursor's page describes moving "an agent from cloud to local to iterate quickly", then back "so it keeps working on its own". From a local session, the subagents page also describes handing one task to a cloud subagent on its own VM and branch with /in-cloud, which runs from the Agents Window.

What travels matters more than the button. Cursor's help centre says "Move to Cloud" does not snapshot local uncommitted changes: the cloud agent starts from a clean git state and gets your conversation history and context, but not dirty files. Commit or stash before you move.

The return trip has conditions. In a community forum reply on 11 Jul 2026, a Cursor staff member said moving a cloud agent to local only existed in the Agents Window, and only appeared when a local agent for the same repository was already open. Cursor 3.7, released on 17 Jun 2026 before that reply, says sessions move "more reliably". Treat the branch as the reliable carrier, because cloud agents always push their work to one, and test the round trip on a real repository before the team depends on it.

From the CLI, prefixing a message with & pushes the conversation to a cloud agent, which you pick up on the web or mobile at cursor.com/agents. The CLI docs show no command for listing or resuming cloud agents.

Keeping context tight and token use down

Cursor Learn says agents "use significantly more tokens than asking simple questions because of all the tool calls and iterations", and its tokens and pricing chapter says output tokens typically cost two to four times more than input tokens. The habits that keep cost down also keep quality up, and the Working with agents chapter gives most of them:

• Start a new conversation when you switch task or the agent starts making mistakes, and reference the old conversation instead of continuing it.
• Use @ mentions when you know which files matter, and skip them when you do not, as Cursor's prompting page advises.
• Plan before building. Cursor Learn calls asking "for too large of a change without planning" one of the most common mistakes, and Cursor's Plan Mode page advises reverting, refining the plan and running it again when a build goes wrong.

Cursor shows where the tokens go. A context ring next to the prompt shows how full the window is, with a breakdown by category, and Cursor compresses older conversation into a summary when the window nears full. In the CLI, /context shows the breakdown and /summarize frees space.

Some costs are structural. Rules are included in every conversation, so Cursor Learn's customising agents chapter advises keeping them short, while skills load only when needed. Subagents isolate context, but Cursor says "Running five subagents in parallel uses roughly five times the tokens of a single agent". By our inference, /best-of-n multiplies spend in the same way, because it runs the task once per model.

On cloud agents, Cursor's cloud agent page says a larger context window can increase token use and cost, and that you will be asked to set a spend limit when you start. The same page says cloud agents are charged at API pricing for the selected model, while Cursor's models and pricing page lists Cloud Agents among the surfaces sharing the weekly usage pool for Cursor's own models. No Cursor page reconciles the two, so check your usage dashboard. Cursor also reported on 23 Sep 2026 that changes to its own harness cut token costs for users by 7% without reducing agent quality, which needs no action from you. Billing, spend caps and model choice are covered in Cursor spend controls and model choice.

A team standard worth writing down

Write the choices down so the whole team works the same way. In our view, a short standard covers:

• Which surface the team uses for which job, using the table above as a starting point.
• A minimum Cursor and CLI version. The NVD records two critical sandbox flaws in Cursor versions before 3.0 (CVE-2026-50548 and CVE-2026-50549, published 25 Jun 2026), fixed by updating to 3.0.
• A committed .cursor/worktrees.json, and for CI a committed permissions file, the restricted autonomy pattern and a named owner for the pipeline's API key.
• A commit-or-stash rule before anyone moves an agent to the cloud.
• A named person for the cloud environment and the cloud agent spend limit.
• The same merge standard for agent work as for human work, with a named approver. Our guides to approval design for AI workflows and the security review an AI agent should pass cover who signs off what.

For the wider rollout, including what to set up before cloud agents, see rolling out Cursor to an engineering team. For how Cursor fits alongside Grok and Grok Bot at SpaceX Super Intelligence (SpaceXSI), start with our guide to SpaceX Super Intelligence for UK business.

Common questions

What is the Cursor Agents Window and how do I open it?

It is Cursor's agent-first interface for running many agents across repositories and environments, with every local and cloud agent listed in one sidebar. Open it from the command palette with Open Agents Window, and use Open IDE to return to the classic editor, or keep both open. It arrived with Cursor 3 on 2 Apr 2026.

Should we use the Cursor CLI or cloud agents for CI?

They do different jobs. The CLI's print mode runs inside your own pipeline with an API key you hold as a secret, and Cursor recommends restricting it with permissions and leaving git and pull request steps to separate workflow steps. Cloud agents run on Cursor's virtual machines and need a prepared environment, connected source control and a plan that includes them. Choose the CLI when your pipeline should own the steps.

Can I move a Cursor agent between local and cloud?

Yes, in the Agents Window, with limits. Move to Cloud sends the conversation but not uncommitted files, so commit or stash first. Moving back needs the Agents Window and, according to a Cursor staff reply in July 2026, an open local agent on the same repository. From the CLI, starting a message with an ampersand hands the conversation to the cloud. Test the round trip before relying on it.

How do I run several Cursor agents at once without conflicts?

Use worktrees. In the Agents Window you start or move an agent into one, in the editor you use the /worktree command, and in the CLI you pass the -w flag. Each worktree is a separate checkout, so use a setup file to install dependencies, remember the default cap of 25 per machine, and note that a worktree does not separate a shared local database or ports.

How do I keep Cursor token use down?

Start a new conversation for each task and reference the old one instead of continuing it, attach only the files that matter, keep always-on rules short, watch the context ring, remember that five parallel subagents use roughly five times the tokens of one, and set a spend limit on cloud agents. Cursor reports that its own harness changes cut token costs for users by 7%, but that is Cursor's figure and not a guarantee.

If you want help setting the standard for your team, or checking whether your repositories are ready for cloud agents, start with our diagnostics, or see our SpaceXSI implementation services and Request a Quote.

John Kelleher holds the SpaceX Super Intelligence Partner Network Accreditation: Forward Deployed Engineer, and the SpaceX Super Intelligence Technical Architect Accreditation.