Skip to content
TBSI.

Start here

  • LLM LeaderboardCompare frontier models on intelligence, price and speedTool
  • What is the best superintelligence?The best frontier model for each jobModels
  • Frontier Gap ReportHow far apart the leading labs areReport
  • MethodologyHow we verify sources, data and claimsAbout

What Is Cursor Agent? Coding Agents, Projects, Modes & Tools (2026)

Cursor Agent, the Agents Window, Projects, Agent Review, Debug Mode, Design Mode and the main tools, explained for developers

By TheBestSuperintelligence Editorial TeamUpdated

◈ Executive Summary

What is Cursor Agent and how do Projects and the Agents Window work?

Cursor Agent is the autonomous coding assistant in Cursor that plans multi-step tasks, edits files, runs terminal commands, searches code and the web, and returns changes for review. Open it with Cmd+I / Ctrl+I. For larger coordinated work, use a Project and its coordinator agent.

☰On this page (13 sections)
  1. 01.What does Cursor Agent do?
  2. 02.What should you know about Cursor Agent first?
  3. 03.How Cursor Agent works
  4. 04.Agents Window
  5. 05.Projects
  6. 06.Agent Review
  7. 07.Debug Mode
  8. 08.Design Mode
  9. 09.Prompting agents
  10. 10.Tools in depth
  11. 11.Where Cursor Agent fits
  12. 12.Limits of this guide
  13. 13.Sources & Further Reading

What does Cursor Agent do?

Cursor Agent is the autonomous coding assistant built into Cursor. It plans multi-step work, searches your codebase, edits files, runs terminal commands, controls a browser, and returns finished changes for you to review. Open the classic side-pane agent with Cmd+I (Mac) or Ctrl+I (Windows/Linux). For larger bodies of work (features, migrations, or multi-PR efforts) use a Project and its coordinator agent.

This guide covers the core Agent, the Agents Window, Projects, Agent Review, Debug Mode, Design Mode, prompting, and the main tools (Terminal, Browser, Search, Canvases, Worktrees). It is written for developers who already live in an IDE and want an agent that stays close to the code rather than a general cloud agent that returns documents or decks.

None of these systems is a verified superintelligence. They are capable multi-step coding tools that still require human ownership of the final result, review of diffs, and proper use of version control.

What should you know about Cursor Agent first?

  • Cursor Agent combines instructions (system prompt + rules), tools (edit, search, terminal, browser, etc.), and the model you select. There is no hard limit on tool calls during a task.
  • The Agents Window (generally available with Cursor 3, April 2026) is the agent-first interface for parallel agents across local, cloud, remote SSH, and multiple workspaces.
  • Projects use a coordinator agent that plans and delegates; it does not write code itself. Projects run on Cloud Agents, keep shared context over months, and can listen to Slack, schedules, or PR activity.
  • Debug Mode generates hypotheses, adds instrumentation, and uses runtime logs to find root causes before making a targeted fix.
  • Design Mode lets you leave notes (and screenshots) on a running app so the agent edits the right UI code without long prose descriptions.
  • Agent Review runs a dedicated review on local changes (Quick or Deep depth). Trigger it automatically, with /agent-review, or from Source Control.
  • Prompting supports @ mentions, Custom Modes, image and voice input, a visible context ring, and mid-conversation model switches.
  • Core tools include Instant Grep, Browser (with console and network access), Terminal (with sandbox and Run Mode controls), Canvases for interactive artifacts, and Worktrees for isolated parallel work.
  • Checkpoints give local rollback points before major changes; they are separate from Git. Use Git for permanent history.

How Cursor Agent works

An agent is built from three components:

  1. Instructions: The system prompt plus any rules that constrain behavior.
  2. Tools: File editing, codebase and web search, terminal execution, browser control, image generation, and more.
  3. Model: The frontier model you choose for the task.

Cursor tunes instructions and tool orchestration for each supported model so you can focus on the software rather than model-specific prompting.

Core tools (overview)

Tool What it does
Search files & folders Find files by name, explore directory structure, locate exact keywords or patterns (powered by Instant Grep)
Web Generate search queries and perform web searches
Fetch Rules Retrieve specific rules by type or description
Read files Read file contents, including images (.png, .jpg, .gif, .webp, .svg) for vision-capable models
Edit files Suggest and apply edits automatically
Run shell commands Execute terminal commands and monitor output (sandbox and Run Mode control when they run)
Browser Navigate pages, interact with elements, take screenshots, read console and network traffic
Image generation Create images from text or reference images (UI mockups, diagrams, assets); saved by default to assets/
Ask questions Pose clarifying questions while continuing to read, edit, or run commands
Canvases Produce interactive artifacts (dashboards, audits, reports) that render beside the chat
Worktrees Run agents in isolated Git checkouts so parallel tasks do not collide

To change the default terminal profile: Command Palette (Cmd/Ctrl+Shift+P) → "Terminal: Select Default Profile".

Checkpoints

Agent automatically creates checkpoints before significant changes. Each checkpoint is a snapshot of every modified file at that moment.

If the agent takes a wrong turn, click any checkpoint in the chat timeline to preview the files, then restore. You can also restore from the "Restore Checkpoint" button on earlier requests or the + button that appears when you hover a message. Restoring reverts files only; conversation history stays intact.

Checkpoints are stored locally and are independent of Git. Use them for safe exploration and iterative work; use Git for permanent version control.

Queued messages and steering a running agent

You can keep talking to Agent while it works.

  • Queue: Type the next instruction and press Enter. Messages appear below the active task and are processed in order after the current work finishes. Drag to reorder.
  • Immediate send: Cmd+Enter / Ctrl+Enter bypasses the queue. The message is appended to the most recent user message and processed at once, useful for urgent redirects.
  • Steer without interrupting: Type a follow-up and choose "Send now" (or press Enter twice in some surfaces). The instruction is delivered at the agent's next safe tool-call boundary so in-flight work is not cut off mid-action. In the CLI, Enter steers at a safe boundary; a second Enter interrupts.

Side chats

Open a side chat with /side or /btw (optionally followed by a question) or the plus button at the top of the chat panel. A side chat is a durable, separate conversation that can still see the parent thread as hidden context. @-mention the side chat from the main thread to pull its context back.

In the Agents Window, press Cmd+K / Ctrl+K to open the command palette and search across past agent transcripts. Cursor maintains a local search index. Inside an open conversation, use Cmd+F / Ctrl+F.

Goals with /goal

By default every message is treated as a new job. Prefix a long-lived objective with /goal:

Text
/goal fix all flaky tests and make CI green

The agent keeps working toward that objective until it is complete. In the CLI, Ctrl+C pauses the goal. You can combine a goal with a Custom Mode (for a fixed playbook) or the built-in /loop skill (recurring or variable-interval execution). /goal is still rolling out; try it in a new chat if you do not see it.

Agents Window

The Agents Window is Cursor's agent-first interface. It provides a unified workspace to build with agents across repos and environments (local, cloud, remote SSH, and more). It combines parallel agents with the depth and control of a development environment.

You can switch back to the classic editor at any time, or keep both open simultaneously.

Open it: From the editor, Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → Open Agents Window.

Return to the IDE: Command Palette → Open IDE. This opens the current workspace in the classic editor.

While staying in the Agents Window you can still search files with Cmd+P / Ctrl+P or search all files with Cmd+Shift+F / Ctrl+Shift+F.

Features available only in the Agents Window

  • Multi-workspace: Work with agents across all your projects from one place.
  • New diffs view: Review and commit changes, and manage PRs without leaving Cursor.
  • Parallel agents: Run many parallel agents in the cloud (and work with them from phone, web, Slack, GitHub, and Linear).
  • Local ↔ cloud handoff: Move an agent from cloud to local for fast iteration, then move it back so it keeps working on its own.
  • Cloud subagents: Hand off a task with /in-cloud, or put a PR on /autopilot, so long-running work runs on its own VM and branch while you keep working locally.
  • Worktrees: Run agents in isolated Git checkouts so each task has its own files and changes.

Choosing between Agents Window and editor

Prefer Agents Window when… Prefer the editor when…
You run and manage many agents in parallel You want the classic IDE with VS Code extensions
You spend more time reviewing diffs and PRs than typing You need flexible screen splitting to see many files at once
You want easier local ↔ cloud handoff and worktrees You are doing focused, hands-on editing

You can move freely between the two interfaces. Both continue to be supported and improved.

Availability: Generally available with Cursor 3 (released 2 April 2026). For the two weeks after launch, Enterprise Admins could control rollout; after the rollout period, all users have access by default.

Projects

A Project is for a larger body of work: a feature, a migration, or a full app. You direct it by chatting with its coordinator agent. The coordinator does not write code itself. It plans the work, delegates it to agents that write the code, and brings the finished work back for you to check.

Projects live in the left-hand nav of the Agents Window and run on Cloud Agents.

Availability: Every plan that includes Cloud Agents (Premium and higher, Teams, Enterprise, and legacy paid Cursor plans). Enterprise teams need Cursor 3.21.9 or later. Not available on Free, Plus, or the legacy Hobby plan, and not available with Privacy Mode (Legacy) because Projects store code in the cloud while they run.

How a Project works

  • The coordinator plans and delegates. It creates and manages agents on your behalf, running as many in parallel as the work needs. Because it delegates rather than executes, it stays responsive to your direction.
  • Agents work inside the Project. Open any agent the coordinator starts to follow its work or talk to it directly.
  • A Project maintains context over months of work, delegates tasks to many agents in parallel, and can perform recurring work without being prompted.

Create a Project

  1. In the Agents Window, find the Projects section in the sidebar and click New Project.
  2. Choose an icon and enter a project name (or leave it as "New Project").
  3. Under Workspace, pick the repository the Project works in. Projects run in the cloud, so the list shows repositories available to your cloud agents. Connect GitHub if it is not already connected. Under Model, pick the model the coordinator uses.
  4. Click Create Project. The Project opens as a chat with its coordinator. Describe what you want built; the coordinator takes it from there.

Projects work best on work that outlives a single chat: a feature with several PRs, a migration, or a job you want handled while you are away.

Add and remove chats

Drag an eligible top-level Cloud Agent chat from the sidebar onto a Project row, or open the chat's sidebar menu and choose Add to Project. Local chats are converted to Remote Control before being added when that action is available. The chat then appears under the Project row and in the Agents list above the Project's chat input.

To remove a chat, open its menu in the Agents list and choose Remove from Project.

Cloud by default, local when needed

A Project runs on its own computer in the cloud, so closing your laptop does not stop it. Running in the cloud also lets a Project run more agents in parallel than a laptop could support. When something needs testing on your machine, the coordinator starts a local agent to run it there.

Shared context

Each Project maintains a set of files that sync across every cloud and local machine its agents use. Agents add research, artifacts, and what they learn about the codebase and how you prefer work to be done. If one agent figures out how to test a service, every future agent can use those instructions. The shared context grows with the Project and makes the coordinator more effective over time.

Subscriptions (event-driven work)

Tell the coordinator to watch a Slack channel, run on a schedule, or follow your pull requests. It then acts on the signals it detects without waiting for your prompt. Example: connect Slack, point the coordinator at a bug-report channel, and it delegates a fix each time a bug comes in.

Once the Project has at least one subscription, a Listening pill appears above the chat input. Click it to see every event the Project listens for (channel messages, PR activity, CI runs, schedules such as every day at 8:00 AM). Remove a subscription from the same list when you no longer need it.

Agent Review

Agent Review runs a dedicated code review on your local changes from inside Cursor.

Setup

  1. Open Cursor Settings.
  2. Go to Agents.
  3. Find Agent Review and configure your preferences.

Starting in Cursor 3.11, this setting moves to Git & PRs > Pull Requests.

Agent Review also reads repository rules from BUGBOT.md files (see BugBot documentation for setup).

You can set it to run automatically after every agent task, or leave it manual and trigger it yourself.

Running a review

Three ways to start a review:

  • Automatic: When enabled in settings, Agent Review runs after every commit is made.
  • Slash command: Type /agent-review in the agent window input to trigger a review on demand.
  • Source Control tab: Open the Source Control tab and run Agent Review to compare all local changes against your main branch. This catches issues across your full set of changes, not only the latest edit.

Review depth

Depth Speed Cost Best for
Quick Fast Low Small diffs, formatting changes, or a fast sanity check
Deep Slow High Complex logic, security-sensitive code, or large refactors

Debug Mode

Debug Mode helps you find root causes and fix tricky bugs that are hard to reproduce or understand. Instead of immediately writing code, the agent generates hypotheses, adds log statements, and uses runtime information to pinpoint the exact issue before making a targeted fix.

When to use Debug Mode

  • Bugs you can reproduce but cannot figure out: The cause is not obvious from reading the code.
  • Race conditions and timing issues: Problems that depend on execution order or async behavior.
  • Performance problems and memory leaks: Issues that require runtime profiling.
  • Regressions where something used to work: You need to trace what changed.

When standard Agent interactions struggle with a bug, Debug Mode provides a different approach that relies on runtime evidence rather than guessing at fixes.

How it works

  1. Explore and hypothesize: The agent explores relevant files, builds context, and generates multiple hypotheses about potential root causes.
  2. Add instrumentation: The agent adds log statements that send data to a local debug server running in a Cursor extension.
  3. Reproduce the bug: Debug Mode asks you to reproduce the bug and provides specific steps. This keeps you in the loop and ensures the agent captures real runtime behavior.
  4. Analyze logs: After reproduction, the agent reviews the collected logs to identify the actual root cause based on runtime evidence.
  5. Make targeted fix: The agent makes a focused fix that directly addresses the root cause, often just a few lines of code.
  6. Verify and clean up: You can re-run the reproduction steps to verify the fix. Once confirmed, the agent removes all instrumentation.

Tips

  • Provide detailed context: error messages, stack traces, and exact reproduction steps.
  • Follow the agent's reproduction steps exactly so the logs capture the real issue.
  • Reproduce multiple times if needed (especially useful for race conditions).
  • Be specific about expected versus actual behavior.

Switching modes

Use the mode picker dropdown in Agent, or press Shift+Tab for quick switching.

Design Mode

Design Mode lets you direct agents by leaving notes on your running app. Open the browser in the Agents Window, click Annotate, and point at what you want changed: an element, an area, or text on the page. Cursor sends each note to the agent with the context it needs, and the agent edits the code while you move on to the next change.

UI work is spatial. Instead of describing a change in a sentence, you point at it. Each note includes the details of what you picked and a screenshot, so the agent can find the right code.

Open Design Mode

Design Mode lives in the browser inside the Agents Window. Click Annotate in the browser toolbar, or focus the browser and press Cmd+Shift+D / Ctrl+Shift+D. The command palette lists the same action as Toggle Design Mode.

Until you open Design Mode for the first time, the Annotate button shows a Try Annotate preview with a short demo. After you have left more than five notes, the button shows only its icon.

A hint row along the top of the page shows the gestures for each step. To exit, click the exit button in the hint row, press the shortcut again, or press Esc. Esc first cancels a markup stroke, a text edit, or an open note, and exits once nothing else is open.

Annotate is available in Cursor 3.24.18 or later. Earlier versions show a pen icon labeled Design Mode in the browser toolbar instead.

Ways to direct the agent

Action How
Select an element Click any element to select it and open a note, then type the change. Use Arrow Up / Arrow Down to move the highlight to parent or child.
Select multiple elements Hold Shift and click more elements to add them to the same note. Useful when the change depends on a relationship between elements.
Mark an area Drag across the page to box an area, then describe the change. Hold Shift to lock to one axis, or Option/Alt to draw from the center. Markup tools: Draw, Ellipse, Rectangle, Arrow. Cmd/Ctrl+Z undoes markup.
Edit text in place Double-click a text element to edit it on the page. Return/Enter saves; Esc reverts. Text edits always wait for Send.
Edit CSS properties On a note for a single element, click Edit CSS properties to open a CSS inspector. Changes are sent with the note.
Dictate a note Once a note has text or CSS edits, use the Dictate button (or hold it while talking).

Send notes

The Batch edits switch in the note card controls whether each note goes to the agent on its own. It starts off.

  • Batch edits off: Press Return/Enter in an element or area note to send it immediately. The button reads Send note.
  • Batch edits on: Notes collect as numbered pins. A Send button with a count replaces Annotate in the toolbar. One click sends every pending note as one message.

Text edits always wait for Send. Open the list next to Send to review pending notes, or remove them all with Clear All. Sending every pending note also exits Design Mode. If you exit with notes still pending, Send stays in the toolbar until you send or clear them.

Cmd/Ctrl+L in a note or text edit puts its content in the chat input instead of sending it. Option/Alt + click an element to add it straight to the chat input (or to the open note).

What the agent sees

Each note gives the agent your text plus:

  • Element details: Tag, id, classes, attributes, CSS-style selector path, first 200 characters of visible text, size and position, and six computed styles (color, background color, font size, font family, display, position). In React, Vue, and Svelte apps the component name and component stack are included.
  • A screenshot: Cropped to the element or to the marked area with your markup drawn on it.

Canvas tabs and older Design Mode

Canvas tabs keep the older pen-icon Design Mode toggle. There, notes go straight to the chat, Batch edits does not apply, and in-place text editing is not available. Drag to draw freehand, or hold Shift and drag to draw a box.

Work in flow

When you refine an interface, one edit usually leads to the next. Design Mode lets you send those edits as you notice them. Point at one element, describe the change, move to another part of the page, and send another note before the first one finishes. Cursor treats a note sent while the agent works like any other queued follow-up. Turn on Batch edits to collect a round of notes and send them together. If your dev server hot-reloads, the changes appear in the running app as the agent finishes.

This flow works best with a fast model that is strong at interface work (Composer 2.5 is recommended in Cursor's own guidance).

Prompting agents

Direct Agent with text prompts in the chat input. You can attach context, images, and voice, and switch models at any point.

@ mentions

Type @ in the chat input to attach specific context. Start typing after @ and Cursor shows matching suggestions.

  • Files & Folders: @auth.ts or @src/components/ (type / after selecting a folder to navigate deeper)
  • Terminals: @Terminals to include terminal output
  • Chats: @Chats to reference context from a previous conversation
  • Git diffs: @Commit (Diff of Working State) for uncommitted changes, or @Branch (Diff with Main) for your full branch diff
  • Browser: @Browser to attach context from the built-in browser

Use @ mentions when you know which files are relevant. If you are not sure which files matter, skip them; Agent finds relevant files through its own search.

Custom Modes

Type / in the chat input to invoke a skill. Pressing Enter attaches the skill to one message and it fades as the conversation moves on.

To keep a skill active as a Custom Mode for the entire session: pick the skill from the / menu and press Option+Enter (Mac) or Alt+Enter (Windows), or select Use as Mode from the skill entry. Inside a mode the skill stays in context on every turn, even as the agent works for hours, until you exit the mode.

Custom Modes work well for skills that describe how to work rather than a one-shot task, for example a code-review checklist or a team playbook such as /tdd held for an entire feature. Available in the Agents Window and the CLI. Any skill with a valid frontmatter block can back a mode; optional icon and color frontmatter fields style the mode's badge.

Image input

Attach images for UI work, debugging, and design implementation:

  • Drag and drop an image file into the chat input
  • Paste from clipboard with Cmd+V / Ctrl+V (including screenshots)

Useful for implementing design mockups, debugging visual issues, and referencing error messages or stack traces without manual transcription.

Voice input

Click the microphone icon in the chat input to dictate your prompt. In the IDE you can also press Cmd+Shift+Space / Ctrl+Shift+Space. In the Agents Window, hold Ctrl+M while you talk. Speak naturally, include technical details such as file and function names, and review the transcription before sending.

Dictation turns speech into text and does not talk back. For a spoken conversation with the agent, start a voice chat from the waveform button instead.

Context usage

Every chat shares a fixed context window with the model. As you add files, run tools, and exchange messages, those tokens fill up. When the window gets close to full, Cursor compresses older parts of the conversation into a summary to leave room for new turns.

The context ring next to the prompt input shows how full the window is. Click the ring to open the breakdown tray, which shows total tokens used by category: System prompt, Tools, Rules, Skills, MCP, Subagents, Summarized conversation, and Conversation (your messages, the agent's replies, and tool results). Hover a segment or row to highlight that category.

Changing models

Use the model picker dropdown at the top of the chat input, or press Cmd+/ / Ctrl+/ to cycle through models. The change applies to the current conversation going forward. Set a default model in Cursor Settings > Models.

  • Faster models work well for quick edits and routine tasks.
  • More capable models are better for complex reasoning and multi-file refactoring.

You can switch models mid-conversation, for example when a faster model handled exploration but you need deeper reasoning for implementation.

Tools in depth

Terminal

Cursor runs shell commands directly in your terminal. Your Run Mode controls when commands run, when Cursor asks, and when terminal commands enter the sandbox.

The sandbox runs terminal commands in a restricted environment that blocks unauthorized file access and network activity. For platform requirements, network modes, environment variables, and sandbox.json configuration, see the Run Modes documentation.

Troubleshooting: Some shell themes (for example Powerlevel9k/Powerlevel10k) can interfere with inline terminal output. If command output looks truncated or misformatted, disable the theme or switch to a simpler prompt when Cursor runs. Detect Cursor sessions with the CURSOR_AGENT environment variable:

bash
# ~/.zshrc
if [[ -n "$CURSOR_AGENT" ]]; then
  # Skip theme initialization
else
  [[ -r ~/.p10k.zsh ]] && source ~/.p10k.zsh
fi
bash
# ~/.bashrc
if [[ -n "$CURSOR_AGENT" ]]; then
  PS1='\u@\h \W \$ '
fi

Browser

Agent can control a web browser to test applications, audit accessibility, convert designs into code, and more. With full access to console logs and network traffic, Agent can debug issues and automate testing workflows.

For enterprise customers, browser controls are governed by MCP allowlist or denylist.

Capabilities: Navigate, Click, Type, Scroll, Screenshot, Console Output, Network Traffic.

Browser state (cookies, localStorage, sessionStorage, IndexedDB) persists between Agent sessions per workspace. Different projects keep separate storage and cookie states.

Efficient design notes:

  • Browser logs are written to files that Agent can grep and selectively read, reducing token usage.
  • Screenshots are integrated with the file-reading tool so the agent actually sees the browser state as images.
  • Agent is prompted to detect running development servers and use the correct ports.

Security:

  • Token authentication and tab isolation per session.
  • Browser tools require approval by default (Manual, Allow-listed, or Auto-run modes).
  • Allow and block lists integrate with Cursor's security guardrails (Cursor Settings → Agents → Auto-Run).
  • Never use auto-run with untrusted code or unfamiliar websites.

Enterprise admins can enable browser features under MCP Configuration and optionally configure a Browser Origin Allowlist that restricts automatic navigation and MCP tool execution to approved origins. Manual navigation by the user is still allowed; once on a non-allowed origin, browser tools are blocked.

Recommended models for browser work include capable frontier models (Sonnet-class, GPT-class, and Auto).

The fastest way to find code is an exact match: a function name, variable, error string, or regex pattern. Agent uses grep automatically when you reference specific symbols.

Cursor ships with Instant Grep, a custom search engine that outperforms ripgrep on large codebases. It runs automatically; no configuration needed. Instant Grep supports full regex and word-boundary matching.

Privacy: Instant Grep builds and queries its index on your machine. Cursor does not upload file paths or code to build a search index and does not store embeddings of your codebase for search. When Agent opens a match, that file content can still be included in the model request.

Explore subagent: Agent can spawn an Explore subagent that runs in its own context window with a faster model. It executes many parallel searches without bloating the main conversation and returns only the relevant findings. Agent uses it automatically when broad search helps; you can also request it ("use a subagent to find all the places we validate user input").

Multi-root workspaces are supported. Each workspace folder's context is available to Agent. Some features that rely on a single git root (for example worktrees) are disabled for multi-root workspaces; Cloud Agents do not support multi-root workspaces.

Canvases

Canvases let Cursor create interactive artifacts that render next to the chat. Instead of scrolling through a long markdown table or code block, you get a standalone view (sections, stats, tables) that you can reopen, edit, and iterate on.

Ask agents for a dashboard, analysis, audit, or report, and Cursor opens the result in a canvas when that is a better fit. Cloud agents can also build canvases as part of their work.

How it works:

  1. Cursor decides the task benefits from a visual or interactive view, or you ask for one directly.
  2. Cursor builds the canvas and inserts a reference in the chat.
  3. You review the rendered view, switch to the source to tweak it, or ask Cursor to change it.
  4. Cursor saves the canvas so you can reopen and rerun it later with fresh data.

Each canvas appears in your workspace's canvas list.

Opening: Click the card at the end of a response, run Open Canvas from the Command Palette (under View), or open a canvas tab from the new-tab menu in the Agents Window.

Sharing: Publish from the canvas toolbar to give teammates a link to a live snapshot (read-only). Available on paid plans (Premium and higher, Teams, Enterprise, and legacy Pro/Pro+/Ultra). Requires a privacy mode that allows data storage (Legacy Privacy Mode blocks it). Team admins can turn shared canvases off. The Shared Canvases page on the dashboard lists canvases you published yourself.

Iterating: Prefer telling Cursor what to change over heavy manual editing. For larger reworks, revert and re-prompt with more detail. Package common canvas workflows as skills (trigger description, layout instructions, data sources, formatting rules) so every teammate gets a consistent layout.

Worktrees

Worktrees let Agent work in isolated Git checkouts. Each task gets its own files, dependencies, and changes while your main checkout stays untouched. Use them when you want several agents on the same repo without conflicts.

The UI-native worktrees feature is available in the Agents Window. In the IDE, use the Worktree Skills commands (/worktree, /best-of-n, /apply-worktree, /delete-worktree).

Create a worktree in the Agents Window: When you start or move an agent into a worktree, Cursor creates a separate checkout. The agent continues inside that checkout. After it finishes, review the result, keep working in the worktree, open a commit/PR from it, or bring the result back into your main workspace.

Setup with .cursor/worktrees.json: Cursor looks for this file in the worktree path, then in the project root. Keys:

  • setup-worktree-unix: Commands or script path for macOS/Linux (takes precedence on Unix).
  • setup-worktree-windows: Commands or script path for Windows.
  • setup-worktree: Generic fallback.

Each key accepts an array of shell commands (run sequentially) or a string path to a script relative to the JSON file. Example:

json
{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Avoid symlinking dependencies into the worktree; prefer fast package managers (bun, pnpm, uv). Debug setup via the Output panel → "Worktrees Setup".

Cleanup (Cursor 3.5+): Cursor can clean up older worktrees automatically. Settings (machine-scoped):

  • cursor.worktreeCleanupIntervalHours: How often to check (default behavior catches up after restarts).
  • cursor.worktreeMaxCount: Maximum worktrees kept per machine (default 25 across all workspaces).

IDE skills:

  • /worktree <task>: Run the rest of that chat in an isolated checkout.
  • /best-of-n model1,model2,... <task>: Run the same task across multiple models, each in its own worktree; compare and then apply or commit the winner.
  • /apply-worktree: Bring changes into the main checkout.
  • /delete-worktree: Remove the isolated checkout when finished.

List all worktrees with git worktree list.

Where Cursor Agent fits

Job Strong fit
Everyday IDE-driven coding, refactoring, debugging Classic Cursor Agent + editor
Many parallel agents, PR/diff-centric workflow, local ↔ cloud handoff Agents Window
Multi-PR feature, migration, or long-running coordinated work Projects (coordinator + Cloud Agents)
Tricky, hard-to-reproduce bugs Debug Mode
Spatial UI iteration on a running app Design Mode
Focused code review of local changes Agent Review (Quick or Deep)
Interactive reports, dashboards, audits Canvases
Parallel experiments without touching main checkout Worktrees / /best-of-n
End-to-end software tickets handed off without living in the IDE Specialized coding agents (e.g. Devin) or general agents

For pure software tickets handed off end-to-end, other specialized coding agents may be a better fit. For everyday IDE-driven development with strong local and cloud agent support, Cursor is the native option.

None of these systems is a verified superintelligence. They finish multi-step coding tasks with tools, but they are not far above the best humans across fields. A person still owns the result, reviews the diffs, and decides what lands in the main branch.

Related reading on this site: Best AI Agents for Work in 2026, What Is Manus?, Manus vs Grok Bot, and the broader guides under Engineering and Ecosystem.

Limits of this guide

Feature availability and exact keyboard behavior can vary by surface (IDE, Agents Window, CLI, cursor.com/agents) and may still be rolling out; /goal is one example. Projects require Cloud Agents and are unavailable on Free, Plus and Hobby plans and with Privacy Mode (Legacy). Design Mode Annotate needs Cursor 3.24.18 or later.

Earlier editions of this guide

Earlier versions of this page, kept in full for reference. Names, prices and figures in them may be out of date; the sections above are the current guide.

More questions from the original guide

How do I review Cursor Agent changes?

Use Agent Review (Settings → Agents, or later Git & PRs → Pull Requests). Run it automatically after commits, with /agent-review, or from the Source Control tab. Choose Quick for small diffs or Deep for complex or security-sensitive changes. Also use checkpoints for local rollback and Git for permanent history.

Is Cursor Agent superintelligent?

No. It is a capable multi-step coding tool that still requires human review, ownership of the final result, and proper version control. No public system has demonstrated verified superintelligence.

Sources & Further Reading

Claim Source Date
Agent tools, checkpoints, queuing and steering, side chats, conversation search, /goal Cursor official documentation: Agent (page URL not supplied) Not dated in the supplied draft
Agents Window features, multi-workspace, parallel agents, worktrees, cloud subagents; generally available with Cursor 3 Cursor official documentation: Agents Window (page URL not supplied) 2026-04-02 (Cursor 3 release)
Projects: coordinator model, shared context, subscriptions, plan availability Cursor official documentation: Projects (page URL not supplied) Not dated in the supplied draft
Agent Review: setup, triggers, Quick and Deep depth Cursor official documentation: Agent Review (page URL not supplied) Not dated in the supplied draft
Debug Mode workflow and Design Mode (Annotate), including the Cursor 3.24.18 requirement Cursor official documentation: Debug Mode and Design Mode (page URLs not supplied) Not dated in the supplied draft
@ mentions, Custom Modes, image and voice input, context ring, model switching Cursor official documentation: Prompting agents (page URL not supplied) Not dated in the supplied draft
Terminal, Browser, Search (Instant Grep), Canvases and Worktrees details Cursor official documentation: tools pages (page URLs not supplied) Not dated in the supplied draft

Frequently asked questions

What is Cursor Agent?

Cursor Agent is the autonomous coding assistant in Cursor that plans multi-step tasks, edits files, runs terminal commands, searches code and the web, and returns changes for review. Open it with Cmd+I / Ctrl+I. For larger coordinated work, use a Project and its coordinator agent.

What is the Agents Window?

The Agents Window is Cursor's agent-first interface (generally available with Cursor 3, April 2026). It unifies local, cloud, and remote agents across workspaces, supports parallel agents, worktrees, local ↔ cloud handoff, and a dedicated diffs/PR view. You can switch back to the classic IDE at any time.

What is a Cursor Project?

A Project is a long-lived body of work directed by a coordinator agent that plans and delegates to other agents. It runs on Cloud Agents, keeps shared context across months, and can react to Slack, schedules, or PR activity. The coordinator does not write code itself.

When should I use Debug Mode?

Use it for bugs you can reproduce but cannot diagnose from the code alone: race conditions, performance issues, memory leaks, and regressions. The agent hypothesizes, instruments, asks you to reproduce, analyzes runtime logs, then makes a targeted fix and cleans up.

What is Design Mode?

Design Mode (Annotate in the Agents Window browser) lets you point at elements or areas of a running app and leave notes, plus screenshots and optional CSS edits. The agent receives structured element details and a cropped screenshot so it can edit the correct UI code. It needs Cursor 3.24.18 or later.

How we sourced this. Draft supplied by the site owner from Cursor's official documentation; not independently re-read by our editors. Facts current as of 2026-11-06. Methodology