Cursor Agent plans and applies changes across files, runs terminal commands, and can drive a browser to check its own work, showing a reviewable diff before you accept. Cmd+I opens it, Shift+Tab rotates into Plan mode, checkpoints snapshot the codebase before significant changes, and queued messages let you stack follow-ups mid-run. Since Cursor 3.0 the Agents Window runs several agents in parallel, isolated by git worktrees.
- Cmd+I opens Agent. Shift+Tab rotates into Plan mode from the chat input.
- It edits across files, runs commands, searches the web, and drives a browser.
- Checkpoints are local and separate from git. Use them for undo, never as version control.
- Queue follow-ups while it works, and reorder them, instead of interrupting.
/worktreegives an agent its own checkout, which is what makes parallel runs safe.
What it is for, and what it is not
| Mode | Scope | Use when |
|---|---|---|
| Tab | The edit you are making | You are typing |
| Inline Edit | A selection or one file | You can point at the change |
| Agent | Many files, plus commands and a browser | You can describe the outcome |
| Plan | Research first, no edits until you approve | The change has more than one reasonable shape |
| Ask | Questions about the codebase | You want to understand, not change |
Agent lives in the sidepane and opens with Cmd+I. From the chat input, Shift+Tab rotates through the modes, so getting into Plan mode costs one keystroke and no menu hunting. Since Cursor 3.0, released on 2 April 2026, agent chats can also be opened as editor tabs, side by side or in a grid, which is how you watch several at once without losing the editor.
What the agent can actually do
Worth knowing precisely, because the failure modes follow from the tool list. Cursor documents the agent as having these capabilities.
From the Cursor agent documentation, checked August 2026.
| Tool | What it means in practice |
|---|---|
| Search files and folders | It finds files you did not name, which is both the feature and the scope-creep risk |
| Read files, including images | It reads before it writes, and long reads are most of what a turn costs. You can paste a screenshot of the bug |
| Edit files | Multi-file diffs you review before accepting |
| Run shell commands | It watches the output, which is what lets it iterate to a passing test rather than guess |
| Browser | Take screenshots, test the application, and verify a visual change it just made |
| Web search | For documentation and error strings it has not seen |
| Image generation | Create visuals from a text description |
| Ask questions | It can stop and ask for clarification instead of guessing |
| Fetch rules | It pulls in matching rules from .cursor/rules/ by type |
The browser tool is the underrated one. An agent building a web page can open it, look at what it shipped, and iterate until the page is right, instead of declaring success against a diff. That closes the loop that used to require you as the eyes, and it is the clearest advantage Cursor has over a terminal agent for front-end work.
Scoping it properly
Same request, two outcomes.
| Weak | Strong |
|---|---|
| "Add authentication" | "Add JWT middleware in src/middleware/auth.ts, apply it to routes under /api/admin, follow the pattern in rateLimit.ts. Do not touch the login route." |
| "Fix the tests" | "Three tests in user.test.ts fail after the schema change. Update the fixtures, not the assertions." |
| "Refactor this component" | "Split Dashboard.tsx into presentational and container components. Behaviour identical, existing tests must pass unchanged." |
| "Make the page look better" | "On /pricing, make the three cards equal height and align the CTA buttons to the bottom. Check it in the browser at 1280 and 390 wide." |
The constraint clause at the end of each strong version is doing most of the work. Agent mode expands scope when it is not told where the edges are, and a diff touching nine unexpected files is how a twenty-minute task becomes an hour of review. Naming the pattern file matters too: it is cheaper for the agent to copy a convention you point at than to infer one from the whole repository.
---
description: Project conventions
alwaysApply: true
---
- Named exports only. No default exports.
- Errors: throw AppError from src/errors.ts, never a bare Error.
- Money is integer minor units, never a float.
- Tests go beside the file as *.test.ts, matching existing style.
- Never edit anything under src/generated/.Steering a run that is already going
Queue the correction rather than interrupting
Cursor lets you stack follow-up instructions while the agent is working, and reorder them. The agent picks each up when the current step finishes, which keeps the run coherent instead of tearing it in half mid-edit.
Stop it the moment the direction is wrong
Do not wait three tool calls to see whether it recovers. The cost of stopping early is one wasted turn; the cost of stopping late is a diff you have to read to find out what happened.
Restore a checkpoint if the run is unsalvageable
Cursor snapshots the state of all modified files before significant changes. Click any checkpoint in the chat timeline to preview the files at that point, then restore. That is faster and cleaner than asking the agent to undo its own work, which tends to produce a second wrong diff on top of the first.
Then shrink the task and start again
A run that needed rescuing was usually too big. Splitting it in half is a better fix than writing a longer prompt for the same scope.
Reviewing what it did
- Read the diff, file by file. Cursor renders it in the editor, which is the best review surface any of these tools offer. Use it rather than skimming the summary.
- Check the deletions. Removed lines get less attention than added ones and are where regressions live.
- Look for files you did not expect. Scope creep shows up here first, and it is the leading indicator that the task was underspecified.
- Run the tests yourself rather than accepting the claim. The agent can run them, but only you can decide whether the tests it changed still test anything.
- Accept in pieces where you can, so the parts you are sure about land and the rest stays under discussion.
Running several agents at once
Two agents editing the same working tree overwrite each other. Cursor solves this the way the terminal agents do, with git worktrees, and since Cursor 2.0 it is built in rather than something you arrange yourself.
From the Cursor changelog and worktrees documentation, checked August 2026.
| Feature | What it does |
|---|---|
| Agents Window | Runs many agents in parallel across repos and environments: locally, in worktrees, in the cloud, and over remote SSH |
/worktree | Creates a separate git worktree so the rest of that chat happens in isolation |
/best-of-n | Runs the same task in parallel across multiple models, each in its own isolated worktree |
/apply-worktree | Brings the changes from a worktree back into your main checkout |
.cursor/worktrees.json | Setup commands for a new worktree, via setup-worktree, setup-worktree-unix, or setup-worktree-windows |
| Cleanup ceiling | Cursor keeps a maximum number of worktrees per machine before cleaning up older ones, defaulting to 25 across all workspaces |
{
"setup-worktree-unix": [
"cp ../main-repo/.env .env",
"pnpm install --frozen-lockfile"
],
"setup-worktree-windows": "scripts/setup-worktree.ps1"
}That file is the difference between parallel agents working and parallel agents failing identically. A new worktree is a clean checkout: no installed dependencies, no untracked environment file, no build cache. Without a setup step, every agent you spawn spends its first three turns discovering that and fixing it badly.
Where a terminal agent still wins
| Need | Cursor agent | Claude Code / Codex |
|---|---|---|
| Reviewing a big change | Better | Terminal diff |
| Editing while reading | Better | Not the shape |
| Checking a visual change | Better, built-in browser tool | Needs an MCP server |
| Worktree isolation built in | Yes, /worktree | You create them yourself |
| Running in CI | Yes, via the Cursor CLI | Mature |
| Long autonomous runs | Workable | Better |
| OS-enforced sandbox | In the CLI | Seatbelt and Landlock in Codex |
Questions people ask
The mode that plans and applies changes across multiple files, runs terminal commands, and can drive a browser, showing you a reviewable diff before you accept it. Cmd+I opens it in the sidepane. Inline Edit works on one selection; Agent works on a whole task.
Press Shift+Tab from the chat input to rotate into Plan mode, or pick it from the mode dropdown. Plan mode asks clarifying questions, examines the codebase, and produces a plan you can edit before any code is written.
Name the files, point at a pattern file to copy, and add a constraint clause saying what must not change. Put repeated conventions in .cursor/rules/ so you are not restating them every time.
Snapshots of all modified files, taken before significant agent changes, which you can preview and restore from the chat timeline. Cursor says they are stored locally, are separate from Git, and should only be used for undoing agent changes. Commit before you start a run.
Yes. Cursor lets you queue follow-up messages while the agent works, and reorder them, so the correction lands at the end of the current step instead of tearing the run in half.
Use the Agents Window, and give each agent its own checkout with the /worktree command. Add a .cursor/worktrees.json setup script so each fresh worktree installs dependencies and copies the environment file it needs, and use /apply-worktree to bring the result back.
For work you are supervising and reviewing in the editor, it is competitive and the review surface is better, especially with the browser tool for visual changes. For CI, long autonomous runs, and OS-enforced sandboxing, the terminal agents fit the shape better.
Yes. It runs shell commands and reads the output, which is what lets it iterate towards a passing state rather than guessing. Run them yourself before accepting anyway, because it can also change the tests.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.