Cursor Agent explained: Agent mode, Plan Mode and Cloud Agents (formerly background agents)

What is the Cursor agent?

Per Cursor's Agent docs, Agent is Cursor's assistant that can complete complex coding tasks independently, run terminal commands and edit code. You open it in the side pane with Cmd+I. It is built from three parts: instructions (the system prompt plus your rules), tools, and the model you pick. Cursor says it tunes the instructions and tools for each frontier model it supports.

The tools are what separate an agent from a chat box. The docs list these, and say there is no limit on the number of tool calls Agent can make during a task.

If you are new to the editor itself, start with what Cursor AI is and how to use Cursor. This page is about the agent and what it can do on its own.

How do you use Agent mode step by step?

1. Open the agent. Press Cmd+I to open the side pane. Pick a model from the model picker, or press Cmd+/ to cycle through models.
2. Describe one task. Say what should change and how you will know it worked. Vague prompts get vague results.
3. Attach context you know matters. Type @ and choose files, folders, terminals, earlier chats, a git diff or the browser. If you are unsure which files matter, skip it. The docs say Agent finds relevant files through its own search.
4. Watch the diff while it works. If it heads the wrong way, click Stop or press Cmd+Shift+Backspace and redirect. You do not have to wait for it to finish.
5. Review before you accept. Run the app, run the tests, then read the diff. The agent saying it is done is not a test.
6. Restore a checkpoint if it went wrong. More on that below.

Two input features are easy to miss. You can paste or drag an image into the prompt, which suits UI work, design mockups and screenshots of error messages. You can also dictate by clicking the microphone icon and reviewing the transcription before sending.

Task: add a dark mode toggle to the settings page.

Context: @src/components/Settings.tsx and @src/styles/theme.css

Requirements:
- The toggle saves the choice in browser storage and applies it on page load.
- Default to the system preference when nothing is saved.
- Do not change any other page.

Done when:
- npm run typecheck and npm test pass.
- I can reload the page and the choice sticks.

If anything is unclear, ask me before you edit files.

When should you use Plan Mode instead of Agent?

Plan Mode creates a detailed implementation plan before any code is written. Press Shift+Tab from the chat input to rotate to it. Cursor says Agent then asks clarifying questions, researches your codebase, writes a plan you can edit through chat or markdown, and builds only when you click to build. Plans save in your home directory by default, and "Save to workspace" moves one into the project for reference and team sharing.

One piece of advice in the docs is worth repeating. When Agent builds something that does not match what you wanted, do not patch it through follow-up prompts. Revert the changes, make the plan more specific and run it again. The docs say this is often faster and gives cleaner results, because the hard part is usually deciding what change to make.

Plan this change, do not write code yet.

Goal: users can export their data as CSV from the account page.

Before you plan:
1. Read how the account page and the existing download code work.
2. Ask me up to five questions you need answered.

The plan must list: files to change, files to create, the order of steps, what could break, and how I verify each step.
Keep it under one page.

How do you steer an agent that is already working?

You have several ways to talk to an agent mid-task, per the docs. Pick by how urgent your correction is.

/goal fix all flaky tests and make CI green

A goal is only as good as its check. "Make CI green" works because CI gives a clear pass or fail. "Improve performance" does not.

How do you undo an agent's mistakes and review its work?

Agent creates checkpoints automatically before significant changes. Click a checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. Restoring reverts files only, not the conversation. Cursor stresses that checkpoints are stored locally and are separate from Git, so use them to undo agent changes and use Git for permanent history.

• Find Issues: after the agent finishes, click Review and then Find Issues for a line-by-line pass over the proposed edits.
• Agent Review: for all local changes, run it from the Source Control tab to compare against your main branch.
• @Branch: tag it in a prompt to hand the agent the diff of your whole branch and ask it to review its own work.
• Bugbot: reviews pull requests automatically when you push, and looks for logic errors, race conditions, missing error handling and security issues. It needs Premium or above.

The docs also give an honest warning: passing tests do not guarantee the code works, because the tests might check the wrong behavior or only the happy path. If a change is too big to review comfortably, break it into smaller pieces. Give the agent verifiable goals such as tests, type checking and linting so it can check its own work.

What are subagents?

When Agent meets a complex task it can launch a subagent: a separate agent that starts with a clean context, works on a task you or the parent describes, and returns a final message. Cursor's subagents docs say they exist to isolate context, run in parallel, specialize and be reusable.

• Built in: Explore searches and analyzes codebases using a faster model, and Browser controls a browser and filters noisy page snapshots down to what matters. You do not configure them.
• Foreground or background: a foreground subagent blocks until it finishes. A background one returns immediately so the work runs in parallel.
• Custom: you can define your own, for example a debugger or a test runner.
• Isolation: subagents share the parent's checkout by default, so several editing at once can overwrite each other. Ask for isolation and each gets its own worktree or cloud environment on its own branch.

Run a swarm of subagents to fix these five flaky tests, each in its own environment

Each subagent costs tokens. Parallel work is faster, not cheaper.

What are Cursor background agents (now Cloud Agents)?

Cursor's docs state that Cloud Agents were formerly called Background Agents. They use the same agent fundamentals but run in isolated virtual machines in the cloud, with a full development environment: cloned repos, installed dependencies, secrets, startup commands and network access. You can run as many in parallel as you want, and they do not need your computer to be online.

Because each has its own machine, a cloud agent can build, test and use the software it changed. The docs say agents can control the desktop and browser, produce screenshots, videos and logs as artifacts, and let you take over the agent's remote desktop to try the result without checking out the branch locally. They support MCP servers and work on a separate branch, then push changes to your repo.

Before anyone can start a cloud agent from a repository, a Cursor account admin has to connect source control (GitHub, GitLab, Bitbucket Cloud or Azure DevOps). You can also pick Start from scratch to begin without a repository. Cursor then creates a draft repository on Origin, its code hosting, and lets you save the work under a name, preview the running app and publish it to a live URL through Vercel.

Setup is the part that decides whether cloud agents are useful. The docs call environment setup the most important step. You can let Cursor's agent configure its own environment from the Cloud Agents dashboard, or commit a .cursor/environment.json. Cloud agents also read AGENTS.md, and the docs recommend a section titled "Cursor Cloud specific instructions" for setup and test commands.

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  },
  "install": "pnpm install"
}

## Cursor Cloud specific instructions
- Install: pnpm install
- Start the dev server: pnpm dev (port 3000)
- Run tests: pnpm test
- Before opening a pull request, run pnpm typecheck and pnpm test and report the result.
- Secrets come from the Secrets tab. Never write secrets into files.

What tasks suit a cloud agent?

A task suits a cloud agent when it is self-contained, has a clear pass or fail, and does not need you at the keyboard. Cursor's docs also say cloud agents try to fix CI failures in pull requests they create, for GitHub Actions only, and stop after 10 follow-ups. Automatic fixing is listed for Teams and Enterprise, so on other plans you ask the agent to monitor and fix CI yourself.

• Fix a bug that has a failing test.
• Add tests for a module that has none.
• Update a dependency and fix what breaks.
• Build a small, well-defined tool. For example, an idea like explain this cron expression in plain English, posted on the board, is one screen with checkable examples.

Task: fix the bug described below and open a pull request.

Bug: [what happens, what should happen, steps to reproduce]

Rules:
- First write a failing test that reproduces the bug. Show me it fails.
- Then fix it with the smallest change that passes.
- Do not touch unrelated files or upgrade dependencies.
- Run the full test suite and linter. Include the output in the pull request description.
- If you cannot reproduce the bug, stop and explain what you tried.

From a local session you can also hand work to a cloud subagent. Type /in-cloud and the next task runs on its own VM and branch, or ask a cloud subagent to take over a pull request with /autopilot. Both run from the Agents Window.

What is the Agents Window?

The Agents Window is Cursor's agent-first interface. Cursor's docs say it is generally available with Cursor 3, released on April 2, 2026. Open it from the command palette with Open Agents Window, and switch back with Open IDE. It adds multi-workspace work, a diff view for review and pull requests, parallel agents, easier handoff between local and cloud, cloud subagents and worktrees, which give each agent an isolated Git checkout.

Projects live there too. A Project has a coordinator agent that plans a larger body of work, such as a feature or a migration, and delegates it to other agents. Projects run on Cloud Agents, so they need a plan that includes them. The docs say the editor is the better fit when you want VS Code extensions and flexible screen splitting, and that both interfaces will keep being supported.

If you are looking for something to point an agent at, the board lists ideas that people posted but will not build, and every idea has a generated build prompt you can paste in as a starting point.