Cursor 3 Complete Developer Guide: Agents Window & Worktrees 2026

Cursor 3, released on April 2, 2026, is the biggest update to the AI-first code editor since Anysphere forked VS Code. The headline feature is the Agents Window — a full-screen workspace that lets you run multiple AI agents in parallel, each isolated in its own git worktree, across local, cloud, remote SSH, and Docker environments. This is not an incremental copilot improvement. It is a structural shift in how a developer IDE thinks about concurrent work. This guide covers every major new capability, the pricing changes that caught early adopters off-guard, and a decision framework for whether Cursor 3 changes your setup versus Claude Code or GitHub Copilot.

What Changed Between Cursor 2 and Cursor 3

Cursor 2 was an AI-assisted editor: you wrote code, the agent suggested completions, you accepted or rejected them one at a time. The workflow was linear. Agent runs had a queue — you could not meaningfully run parallel investigations without switching between multiple separate windows.

Cursor 3 inverts this model. The editor becomes a coordination layer for multiple concurrent agents. Key structural changes:

• Agents Window: A full-screen, tiled workspace for managing multiple active agents simultaneously. Think of it as a terminal multiplexer, but for AI agent sessions.
• Automatic git worktree management: Each agent in the Agents Window gets its own isolated git worktree, preventing file conflicts between parallel runs.
• /multitask: Breaks a large task into sub-tasks and dispatches them to a fleet of async subagents running in isolation.
• /best-of-n: Runs the same task across N models simultaneously, each in an isolated worktree, then lets you compare and cherry-pick outputs.
• Design Mode: Annotate UI elements directly in a live browser preview, giving agents pixel-precise targeting instructions.
• Multi-root workspaces: A single agent session can now span multiple repositories simultaneously — frontend, backend, and shared library in the same context.

The Agents Window: Architecture and Setup

Opening the Agents Window (Cmd+Shift+A on macOS, Ctrl+Shift+A on Windows/Linux) replaces the standard editor layout with a full-screen workspace divided into tiles. Each tile represents one active agent session. The default tiled layout runs up to six agents simultaneously on a standard display; you can collapse completed sessions to free space for running ones.

Each agent tile shows:

• The current step in the agent’s plan, expanded or collapsed
• The active files the agent has read or modified in its worktree
• A minimal terminal output stream showing tool calls as they execute
• A git diff indicator showing a live count of changed lines in the agent’s isolated branch

When an agent completes a task, its tile shows a summary diff. You can Review (opens a standard diff viewer), Apply (merges the worktree changes into your main branch), or Discard. Applying is always a deliberate action — agents never auto-merge into your working tree without confirmation.

To start a new agent session from the Agents Window, click the + Agent button, choose a model and environment (local worktree, cloud VM, remote SSH host, or Docker container), then type your task description. Background agents running on cloud VMs continue executing even when you close the editor entirely.

Parallel Agents and Git Worktrees

The Agents Window’s most technically significant feature is automatic git worktree management. When you run multiple agents simultaneously, each gets its own worktree — a separate checkout of your repository at the same base commit. Agents cannot read or modify each other’s files. Merge conflicts only arise at apply time, when you deliberately bring a completed worktree back into your main branch.

This solves a real problem from Cursor 2: if you ran two agents sequentially and the first left the codebase in a broken intermediate state, the second inherited that damage. With isolated worktrees, each agent starts from a clean baseline. A failing experiment in one tile cannot corrupt a passing solution in another.

The /worktree command creates a named worktree manually for longer-running investigations you want to preserve between sessions. /apply-worktree <name> brings those changes back into your current branch with a merge commit or cherry-pick, your choice.

One practical workflow Cursor’s own docs highlight: use /best-of-n 3 to run a refactoring task across three models — GPT-5.4, Claude Opus 4.7, and Gemini 3.1 Pro, for example — then review which output you prefer before applying any of them. This is genuinely useful for architecture decisions where you want multiple independent approaches before committing to one direction.

The /multitask Command

The /multitask command is the Agents Window’s answer to task parallelization. When you give it a large task — “add unit tests for all functions in the auth module” — it analyzes the request, breaks it into independent sub-tasks, and dispatches each to a separate async subagent running in its own worktree. The parent session waits for all sub-tasks to complete, then presents a consolidated summary diff you can review in aggregate before applying anything.

In practice, /multitask works best for tasks that are naturally partitionable with minimal interdependency:

• Writing tests for independent functions or modules
• Adding documentation comments across a large codebase
• Running security audits on isolated API endpoints
• Generating localization strings for independent UI components
• Applying a consistent formatting or naming convention across separate files

Tasks with heavy interdependency — like a database schema migration requiring coordinated changes across models, migrations, and API handlers — are better handled in a single agent session with a detailed sequential plan, not split across subagents that cannot see each other’s intermediate state.

Design Mode

Design Mode is available inside the Agents Window for any agent session configured with browser access. When enabled, it opens a live preview panel alongside the agent tile. You can annotate elements in the preview directly: click an element, draw a bounding box around a region, add a text label, and the annotation is automatically embedded in the next agent message as a precise visual reference.

This replaces the previous workflow of copying CSS selectors or pasting screenshots and describing what you want in words. Instead of “the submit button in the payment form is too close to the input field on mobile,” you annotate the exact element and type “add 16px margin-top.” The agent sees exactly what you’re pointing at without any ambiguity in the description.

Design Mode is most useful for frontend iteration workflows where the gap between designer intent and implemented output requires multiple rounds of corrective feedback. It significantly reduces the back-and-forth that was common when using natural language descriptions to guide specific CSS or layout adjustments.

Multi-Root Workspaces

Cursor 3’s multi-root workspace support allows a single agent session to span multiple repository roots simultaneously. In practice, this means you can add a frontend repo, backend repo, and shared component library as roots in one workspace, and an agent in that context can make cross-repo changes — updating an API contract and the client consuming it — in a single coordinated session.

This matters for organizations with monorepo-adjacent structures: multiple separate repos that are tightly coupled but not merged for organizational or legacy reasons. Previously, coordinating a change across three repos required three separate agent sessions with manual handoffs. Multi-root workspaces collapse that into one session with full cross-repo context.

Setup is straightforward: File → Add Folder to Workspace, or pass multiple paths on the command line as cursor ./frontend ./backend ./shared-lib. Each root is indexed independently, but an agent’s context window can draw from all roots simultaneously when planning and executing cross-repo changes.

Pricing: What the Launch Documentation Missed

Cursor 3 launched with four tiers:

• Free: 50 agent messages per day, no cloud agents, local worktrees only
• Pro ($20/month): 500 agent messages per day, 30 cloud agent hours per month, standard models
• Pro+ ($60/month): Unlimited agent messages, 200 cloud agent hours per month, premium models including Claude Opus 4.7 and GPT-5.4
• Ultra ($200/month): Everything in Pro+, unlimited cloud agent hours, priority compute queue

The launch pricing page did not prominently disclose that cloud agents running on Cursor-hosted VMs consume compute credits at a per-minute rate beyond the included hours. Early adopters running large /multitask workflows on cloud VMs reported exceeding their included hours and being billed at overage rates, with some reporting over $2,000 in charges within two days before noticing. Cursor has since updated the pricing page to surface the per-minute overage rate and added a per-team spending limit setting — but this remains a significant watch point for teams enabling cloud execution at scale.

For local agent execution on your own machine, there are no additional compute charges beyond the per-message model costs included in each tier. Running /multitask and parallel worktrees locally falls within the standard message quota. For most developers, Pro at $20/month is the right entry point to evaluate the Agents Window before committing to higher tiers. Only upgrade to Pro+ if you are consistently hitting the 30-hour cloud agent cap each month.

Cursor 3 vs Claude Code vs GitHub Copilot

Cursor 3, Claude Code, and GitHub Copilot are all converging on multi-agent execution from different starting points. The right tool depends on how your team actually works, not which benchmark leads on a given week. For a detailed breakdown with cost projections, see the Claude Code vs Cursor vs Copilot for Agencies guide.

Choose Cursor 3 when:

• Your team is editor-centric and wants the IDE itself to manage agent coordination rather than a terminal workflow
• Design Mode is valuable for frontend-heavy workflows where visual annotation speeds up iteration
• Multi-root workspaces solve a real cross-repo coordination problem on your team
• You want model flexibility — Cursor 3 supports GPT-5.4, Claude Opus 4.7, Gemini 3.1 Pro, and DeepSeek V4 Pro from a single interface

Choose Claude Code when:

• You prefer a terminal-native workflow with deep MCP server integration
• Your team uses custom agent skills through Claude’s skill system and wants composable tooling
• You need the strongest single-agent performance on complex, long-horizon engineering tasks where context depth matters more than parallelism

Choose GitHub Copilot when:

• Enterprise contracts, SSO requirements, and GitHub organization policy enforcement dictate the tool choice
• Predictable per-seat pricing with no compute overages is a hard budget requirement
• Zero workflow change for VS Code or JetBrains users is a non-negotiable constraint

For developers who want to quantify the tradeoff before deciding, the Coding Assistant ROI Calculator runs side-by-side cost projections for each tool against your team size and usage patterns.

Getting Started with Cursor 3

Upgrading from Cursor 2 migrates existing projects and settings automatically on first launch — no configuration migration required. The Agents Window is hidden by default on upgrade. Enable it from View → Agents Window, or add "agents.window.default": "open" to your Cursor settings JSON to open it automatically on every project launch.

A recommended first workflow to build intuition for parallel agents:

1. Open the Agents Window with Cmd+Shift+A (macOS) or Ctrl+Shift+A (Windows/Linux)
2. Use /best-of-n 2 to run a small, well-scoped refactoring task across two different models
3. Review the diff comparison panel once both agents complete — each result is in its own isolated worktree
4. Use Apply on the output you prefer, or open both diffs and combine the best parts manually

This gives you direct experience of how worktree isolation and parallel execution work before scaling up to /multitask on larger tasks where the cost and time savings become material.

What to Watch Over the Next 60 Days

Cursor’s April 24 changelog — released three weeks after the main Cursor 3 launch — shipped /multitask and improved multi-root workspace support as additions to the Cursor 3 base, signaling active iteration on the Agents Window feature set. Several community-requested capabilities are on the public roadmap: persistent agent memory across sessions (agents currently start fresh on each new task), an API for programmatic agent invocation outside the editor UI, and native MCP server support inside the Agents Window for tool-augmented agents.

The cloud agent pricing transparency issue remains the most significant friction point for broad Pro+ and Ultra adoption. Showing per-task cost estimates before agents start running — rather than after the billing cycle — would remove the primary reason enterprise teams are cautious about enabling cloud execution at scale.

For complementary reading on multi-agent coordination patterns that apply regardless of which IDE you use, the Claude Code Multi-Agent Coordination guide covers the orchestration concepts behind agent parallelism, context handoffs, and task decomposition in depth.