04 - Plan Mode and Background Agents: Work Smarter, Not Just Faster
There is a specific moment when many developers realize that standard Agent Mode is not enough. The prompt is correct, the context is provided, but the agent starts writing code immediately before truly understanding the problem. It adds unnecessary files, modifies classes it should not have touched, and after twenty minutes of autonomous execution you end up with a codebase that technically works but has grown in the wrong direction.
Cursor's answer to this problem is called Plan Mode. Before writing a single line of code, the agent analyzes the project, asks clarifying questions, generates a structured Markdown plan and asks for your approval. Only once you have reviewed and validated every step does the execution begin. It is a radically different philosophy: think before you code.
Alongside Plan Mode, Cursor 2.0 introduced Background Agents: AI processes that work in parallel on isolated git branches via worktrees. While you write code on the main branch, up to eight agents can simultaneously work on different tasks, each in a completely separate environment, without interfering with your work or with each other.
In this Advanced article we will explore both features in depth: how they work, when to use them, how to combine them, and which patterns are most effective for complex development workflows.
What You Will Learn in This Article
- How Plan Mode changes the paradigm of AI-assisted development
- The complete workflow: from prompt generation to plan approval
- What a Background Agent is and how git worktrees work in Cursor
- How to launch up to 8 parallel agents with Cursor 2.0
- Mission Control: monitoring and managing running agents
- Practical use cases: feature scaffolding, parallel bug fixes, migration projects
- Long-running agents: limits, best practices and cost management
- How Cursor Rules guide the generated plan
- Real limitations and workarounds tested in production
Position in the Series: Cursor IDE and AI-Native Development
| # | Article | Level |
|---|---|---|
| 1 | Cursor IDE: Complete Guide for Developers | Beginner |
| 2 | Cursor Rules: Configure AI for Your Project | Intermediate |
| 3 | Agent Mode: Modify the Codebase with a Single Command | Intermediate |
| 4 | Plan Mode and Background Agents (you are here) | Advanced |
| 5 | Cursor Hooks: Automate Your Workflow | Intermediate |
| 6 | MCP and Cursor: Connect Your IDE to Databases and APIs | Advanced |
| 7 | Debugging with Cursor AI: 3x Faster | Intermediate |
| 8 | Cursor vs Windsurf vs Copilot in 2026 | Beginner |
| 9 | Professional Workflow: Angular Project with Cursor | Advanced |
What Is Plan Mode and How It Differs from Agent Mode
To understand Plan Mode, you first need to understand the problem it solves. In standard Agent Mode, the flow is direct: you give an instruction, the agent reads relevant files and immediately starts implementing. This approach is efficient for well-defined, scoped tasks but systematically fails on complex or ambiguous problems.
Imagine asking an agent: "Refactor the authentication module to support OAuth2 with Google and GitHub". An agent in normal mode might start modifying existing authentication files without knowing that you use JWT, that you have a custom middleware, or that the architecture uses server-side session management. The result is code that is correct in the abstract but wrong in the context of your project.
The "Think Before You Code" Philosophy
Plan Mode introduces a deliberation layer before execution. When you activate Plan Mode, the agent does not write code: it asks questions, researches the codebase, identifies dependencies and constraints, then produces a structured document that describes exactly what it intends to do, file by file, step by step.
The plan is an editable Markdown file. You can modify it, remove steps you disagree with, add constraints the agent did not consider, and correct wrong assumptions. Only when you are satisfied do you click "Build" and execution begins, guided by the approved plan.
When to Use Plan Mode vs Agent Mode
The choice between the two modes depends primarily on the complexity and ambiguity of the task:
Mode Selection Guide
| Task Characteristic | Recommended Mode |
|---|---|
| Simple, well-defined task (bug fix, adding a function) | Direct Agent Mode |
| Complex feature touching multiple modules | Plan Mode |
| Architectural refactoring | Plan Mode (mandatory) |
| Migration (framework, database, library) | Plan Mode + Background Agents |
| Task you know well and have done before | Agent Mode with specific Rules |
| Unknown or inherited codebase | Plan Mode always |
| Structured boilerplate generation | Plan Mode or Agent with templates |
How Plan Mode Works: From Prompt to Executable Plan
Plan Mode is activated by pressing Shift + Tab in the agent input field, or is automatically suggested by Cursor when it detects a complex request. Once activated, the flow unfolds in four distinct phases.
Phase 1: Research and Codebase Analysis
The agent does not start from the prompt: it starts from the codebase. Using the same tools as Agent Mode (semantic search, file reading, grep), it explores the project to understand the context. It identifies relevant files, reads existing documentation, analyzes dependencies and relationships between modules.
During this phase, the agent can ask clarifying questions. If your request is ambiguous on a critical point, it asks you to specify before proceeding. These questions are valuable: they often reveal implicit assumptions you had not considered.
Phase 2: Plan Generation
Once analysis is complete, the agent generates a structured Markdown document. The plan includes: a summary of the objective, an analysis of involved files, a numbered list of steps with detailed descriptions, paths of files to be created or modified, and potential risks or dependencies to handle.
With Cursor 2.2, plans can also include Mermaid diagrams automatically generated to visualize flows, architectures and relationships between components.
Here is an example of a generated plan for an authentication refactoring:
# Plan: Authentication Refactoring with OAuth2
## Objective
Add OAuth2 support (Google and GitHub) to the existing authentication system,
maintaining compatibility with the current email/password flow.
## Codebase Analysis
- Auth files: src/auth/auth.service.ts, src/auth/auth.guard.ts
- JWT handled in: src/middleware/jwt.middleware.ts
- Session management: server-side (express-session)
- Database: PostgreSQL with `users` table (id, email, password_hash, created_at)
## Steps to Execute
### Step 1: Add OAuth2 Dependencies
- [ ] Install `passport`, `passport-google-oauth20`, `passport-github2`
- [ ] Update package.json and package-lock.json
- File: package.json
### Step 2: Configure OAuth Strategy
- [ ] Create src/auth/strategies/google.strategy.ts
- [ ] Create src/auth/strategies/github.strategy.ts
- [ ] Update src/auth/auth.module.ts to register new strategies
- Files to create: 2 new, 1 modified
### Step 3: Database Schema Migration
- [ ] Add `oauth_provider` and `oauth_id` columns to users table
- [ ] Create migration: db/migrations/20251205_add_oauth_fields.sql
- [ ] Update User entity to reflect new fields
- Files: User.ts, new migration
### Step 4: Update Routes and Controller
- [ ] Add endpoint GET /auth/google and GET /auth/google/callback
- [ ] Add endpoint GET /auth/github and GET /auth/github/callback
- [ ] Update auth.controller.ts
- Files: auth.controller.ts, app.routes.ts
### Step 5: Testing and Validation
- [ ] Update existing tests for compatibility
- [ ] Add integration tests for OAuth flow
- Files: auth.spec.ts, new test files
## Identified Risks
- DB migration requires a preventive backup in production
- Callback URLs must be configured in Google/GitHub developer consoles
- OAuth secrets must be added to environment variables
## Files NOT Modified
- src/middleware/jwt.middleware.ts (compatibility preserved)
- Frontend components (out of scope for this plan)
Phase 3: Plan Review and Editing
The plan opens as a Markdown file in the editor. You can modify it directly: remove unnecessary steps, add constraints, correct file names, specify alternative approaches. This is the most important phase: your intervention determines the quality of the subsequent execution.
Common Mistake to Avoid
Do not approve the plan without reading it. The temptation to click "Build" right away is strong, but this is precisely where Plan Mode differs from Agent Mode: your review is an integral part of the process. An approved plan without review is worse than direct Agent Mode, because it gives you a false sense of control.
Phase 4: Plan-Guided Execution
Clicking "Build", Cursor enters Agent Mode but with the plan as a structured guide. The agent executes steps in the defined order, using the plan as a reference "specification". You can monitor progress in real time: each completed step is marked, and the agent signals any deviations from the original plan.
If an unexpected problem arises during execution, the agent stops and asks for instructions rather than autonomously proceeding toward a potentially incorrect solution.
Background Agents: Architecture and How They Work
While Plan Mode solves the problem of execution quality, Background Agents solve the problem of speed and parallelism. Introduced with Cursor 2.0 in November 2025, they allow running up to eight agents simultaneously, each in a completely isolated git environment.
Git Worktrees: The Underlying Technology
Background Agents are built on git worktrees, a native git feature that allows having multiple working directories associated with the same repository, each on a different branch. Unlike a traditional clone (which duplicates the entire repository on disk), a worktree is lightweight: it shares the git object store and only requires space for files that actually differ between branches.
For Cursor, this means each Background Agent has:
- A dedicated git branch on which it works in isolation
- A separate working directory on the local filesystem
- A separate codebase index for semantic search
- No interference with your work or other agents
The result is that you can work on the main branch while three agents
simultaneously modify feature/auth, feature/dashboard and fix/performance, without
ever running into conflicts.
Launching Background Agents with Cursor 2.0
There are two main approaches to starting parallel agents. The first and most common: from the Composer panel, open a new agent tab and assign it a specific task. Each tab represents an independent agent that can work in the background.
The second approach, introduced with Cursor 2.0, allows launching multiple agents from the same prompt: the main agent receives the instruction, decomposes it into subtasks and spawns child agents that work in parallel on each subtask. Child agents can now be asynchronous, allowing the parent to continue while children execute.
# Workflow with 3 Parallel Background Agents
## Initial Setup
# Enable worktrees display in SCM panel (optional)
# Cursor settings.json:
{
"git.showCursorWorktrees": true
}
## Main branch (your normal work)
$ git branch
* main
feature/auth-oauth
feature/dashboard-redesign
fix/api-performance
## Worktree structure (automatically managed by Cursor)
$ git worktree list
/home/user/myproject abc1234 [main]
/tmp/cursor-agent-1/myproject def5678 [feature/auth-oauth]
/tmp/cursor-agent-2/myproject ghi9012 [feature/dashboard-redesign]
/tmp/cursor-agent-3/myproject jkl3456 [fix/api-performance]
## Each agent works in its isolated worktree
# Agent 1 - OAuth2 implementation
# Prompt: "Implement OAuth2 with Google following the auth-plan.md"
# Agent 2 - Dashboard redesign
# Prompt: "Refactor the dashboard component with new charts for D3.js"
# Agent 3 - Performance fix
# Prompt: "Optimize N+1 queries in orders module identified by profiler"
## On completion, branches are ready for review and merge
$ git diff main...feature/auth-oauth
$ git diff main...feature/dashboard-redesign
$ git diff main...fix/api-performance
Asynchronous Agents and Recursive Spawning
One of the most significant changes in Cursor 2.2 is the ability for agents to work in a fully asynchronous manner. In previous versions, when a parent agent spawned sub-agents, it had to wait for each to complete before proceeding. Now the parent can continue while children work in parallel.
Even more powerful is the ability of sub-agents to spawn their own sub-agents, creating a coordinated work tree. A parent agent can delegate feature A to a child, which in turn splits the work between a grandchild for tests and a grandchild for implementation. Cursor manages tree synchronization and presents results to you in a coherent way.
Mission Control: Monitoring Parallel Agents
With multiple agents working simultaneously, it becomes critical to have visibility on what is happening. Cursor 2.0 redesigned the interface with an agent-centered paradigm: instead of managing files, you manage processes.
The Agents Panel
In Cursor's sidebar you find the active agents panel. For each agent, the following are shown:
- Name and task assigned (derived from the initial prompt)
- Git branch it is working on
- Status: running, waiting for input, completed, in error
- Last executed step with detailed log
- Modified files in the current session
- Tokens consumed and cost estimate
Interacting with Running Agents
You can click on any agent to open its chat history, see the files it has modified, give new instructions, or stop execution. If an agent is stuck or heading in the wrong direction, you can stop it with a click and redirect it with a new message.
Useful Shortcuts for Mission Control
| Action | Shortcut / Method |
|---|---|
| New background agent | Cmd+Shift+N in Composer panel |
| Switch between agents | Click in agents panel or Cmd+Shift+Tab |
| Activate Plan Mode for agent | Shift+Tab in the agent input |
| Stop running agent | Click stop button in agent header |
| Review agent diff | Click "Changed files" in agent panel |
| Enable worktrees display in SCM | Setting git.showCursorWorktrees: true |
Practical Use Cases
Case 1: Feature Scaffolding with Plan Mode
The typical scenario: you need to add a complete module to an existing application. Without Plan Mode, the agent might generate the module using different conventions from the rest of the project or ignore established architectural patterns.
With Plan Mode, the flow is:
- Open Composer and press Shift+Tab to activate Plan Mode
- Describe the feature: "Add Notifications module with real-time via WebSocket, user preference management and history"
- The agent analyzes the project: identifies existing patterns, naming conventions, module architecture
- It asks questions: "Does the project use Redux or Context API for state management?", "Should I include tests or do you handle them separately?"
- It generates the plan with the exact file structure, respecting the project's conventions
- You review, optionally removing steps (e.g., "do not add Storybook stories, we don't use them")
- Click Build and the module is scaffolded correctly on the first attempt
Case 2: Parallel Bug Fixes with Background Agents
You have a list of 4 isolated bugs, each in different modules of the application. Instead of fixing them sequentially, you can parallelize:
# Example: 4 bug fixes in parallel
## Agent 1: Fix form validation
# Branch: fix/form-validation
# Prompt: "The registration form accepts invalid emails.
# File: src/components/RegisterForm.tsx
# Add RFC 5322 validation and show inline error"
## Agent 2: Fix query performance
# Branch: fix/slow-dashboard-query
# Prompt: "The dashboard takes 8s to load.
# File: src/api/dashboard.service.ts, line 45
# Query has N+1 on orders->items. Add eager loading"
## Agent 3: Fix mobile layout
# Branch: fix/mobile-navbar
# Prompt: "On viewport < 768px the navbar overlaps content.
# File: src/components/Navbar.css
# Z-index and position sticky are conflicting"
## Agent 4: Fix error handling
# Branch: fix/error-boundaries
# Prompt: "App crashes without error boundary.
# Add React ErrorBoundary to router and critical modules"
## Result after ~15 minutes:
## 4 branches ready, each with its isolated fix
## Sequential review and merge or with stacked PRs
The advantage is not only in time. With fixes isolated on separate branches, code review is much simpler: each PR touches a single problem, the diff is minimal and comprehensible.
Case 3: Migration Project with Plan + Background Agents
The most powerful use case: a complex migration that requires both accurate planning and parallelism. For example, migrating an application from JavaScript to TypeScript.
The optimal workflow:
- Use Plan Mode to generate the complete migration strategy
- The plan identifies 30 files, grouped into 4 dependency clusters
- Launch 4 Background Agents, one per cluster
- Each agent has as context the general plan plus its subset of files
- While agents work, you monitor from Mission Control and handle conflicts
- On completion, review the 4 branches and merge in the correct order
Long-Running Agents: How They Work and What to Expect
Cursor's Background Agents can work for extended sessions, even while you have closed the IDE. This feature is particularly useful for tasks that require tens of minutes or more, such as migrations, large-scale test generation or in-depth codebase analysis.
Session Continuity
Unlike a simple chat window, a Background Agent maintains its state between sessions. You can start an agent, close your laptop, and when you return the agent has continued working (if configured to run on remote machines). Cursor supports both local execution (the process stops when you close the IDE) and remote execution (the agent continues on cloud infrastructure).
Token Limits and Cost
Long-running agents consume many tokens. It is important to monitor consumption to avoid billing surprises. Cursor shows real-time token consumption for each agent in the Mission Control panel.
Watch Out for Parallel Agent Costs
Each Background Agent consumes tokens independently. Launching 8 agents in parallel can consume 8 times the tokens of a single agent in the same period. On the Pro plan ($20/month) you have a monthly cap: manage parallelism judiciously. Use parallel agents for tasks that genuinely benefit from parallelization, not as a default for every operation.
Plan Mode and Cursor Rules: A Powerful Synergy
Plan Mode does not operate in isolation: it is strongly influenced by the Cursor Rules configured in the project. When the agent generates a plan, the rules act as constraints and guides that shape its content.
How Rules Guide the Plan
If you have defined rules like "always use clean architecture with 3 layers" or "every new feature must include unit tests with Jest", the generated plan will automatically reflect these constraints. The agent will not propose putting business logic in the controller if the rules specify separation of concerns.
# Example: .cursor/rules/architecture.mdc
---
alwaysApply: true
---
# Project Architecture
## Layer Separation (MANDATORY)
- Controllers: routing and input validation only
- Services: business logic and orchestration
- Repositories: data access, zero business logic
- DTOs: data transfer between layers, typed
## Naming Conventions
- Service: `*.service.ts`
- Repository: `*.repository.ts`
- DTO: `*-request.dto.ts`, `*-response.dto.ts`
- Controller: `*.controller.ts`
## Testing Requirements
- Unit test for every Service (min 80% coverage)
- Integration test for every Repository
- Test file: `*.spec.ts` in the same directory
## When Plan Mode generates a plan with this rule active:
## - Each step creates files in the correct layer
## - Names follow the defined conventions
## - Tests are included as a separate step in the plan
## - No code is ever suggested that crosses layers incorrectly
Rules to Optimize Plans
You can also create rules specifically for Plan Mode that guide the structure of the plan itself, not just the implementation:
# Example: .cursor/rules/planning.mdc
---
alwaysApply: true
---
# Planning Guidelines
## Before generating a plan, you MUST:
1. Identify all files that will be modified
2. Verify if there are tests to update
3. Check if DB migrations are needed
4. Evaluate impact on existing APIs
## Plan Structure (MANDATORY)
Every plan must contain:
- ## Objective (1 paragraph)
- ## Impact Analysis (files, dependencies, risks)
- ## Implementation Steps (numbered, with file paths)
- ## Testing (unit + integration)
- ## Files NOT Modified (explicit list)
- ## Rollback Strategy (how to undo if things go wrong)
## Step Size
- Each step must be atomic (completable in 10-15 min)
- Steps that are too large should be broken into sub-steps
- Avoid steps that depend on the state of parallel steps
Real Limitations and Workarounds
Plan Mode and Background Agents are powerful features but are not without limitations. Knowing the limits is just as important as knowing the capabilities.
Plan Mode: Hallucinations in the Plan
The plan can contain errors: nonexistent file paths, wrong assumptions about the architecture, redundant or missing steps. The agent does its best to understand the project, but if the codebase is large or poorly documented, it can make mistakes.
Workaround: Force the agent to cite exact paths during analysis. Add to the prompt: "Before generating the plan, list the files you found in your search and confirm they are correct". This "checkpoint" significantly reduces errors in the final plan.
Background Agents: Merge Conflicts
If two agents modify the same file on different branches, at merge time you will have conflicts. Cursor does not automatically manage semantic reconciliation: merging is your responsibility.
Workaround: Before launching parallel agents, analyze the plan and ensure that the tasks are truly independent. If two agents need to touch the same file (e.g., a central routing file), sequence that specific task and parallelize the rest.
Long Context in Long Plans
For very large projects, the generated plan can become so long that it does not fit in the agent's context window during execution. The result is that the final steps of the plan are executed with less context and may be less precise.
Workaround: Break large plans into smaller ones. Use Plan Mode to generate a "meta-plan" that identifies the main phases, then use Plan Mode again to generate detailed plans for each phase. This cascading approach keeps context manageable for every step.
Agents Blocked by External Dependencies
An agent that needs, for example, to query a database or call an external API to complete its task will get stuck if these resources are not accessible in the local or remote development environment in which it runs.
Workaround: Use Cursor Rules to specify how to handle external dependencies: "If you need real data from the DB, use the file fixtures/sample-data.json as a mock". This allows agents to proceed even without direct access to external resources.
Best Practices for Plan Mode and Background Agents
1. Systematic Plan Review
Establish a plan review process before executing it. Do not just skim quickly: verify that each step is reasonable, that the identified files actually exist, that the execution order is correct. A well-reviewed plan almost always translates into a correct execution.
2. Commit Before Starting Agents
Before launching any agent (in Plan Mode or Background), always commit your current work. Git worktrees branch from your current HEAD: a clean working directory ensures that agent branches start from a known and stable state.
3. Granular Tasks for Parallel Agents
An agent works best with a well-defined and scoped task. Resist the temptation to give the agent enormous tasks ("Implement the entire e-commerce module"): break them into smaller tasks that you can parallelize. Well-granulated parallelism is more reliable than monolithic parallelism.
4. Use Plan Mode for the First Time on a Codebase
When working on a codebase you do not know well (an inherited project, an open source you are contributing to, a new client), always use Plan Mode for the first tasks. The generated plan will give you a quick overview of the project's architectural patterns, even if you ultimately decide not to execute it.
5. Cost Optimization
Not all tasks require Plan Mode. Use it selectively for complex tasks. For simple tasks (rename variable, add import, fix typo in document), direct Agent Mode is more efficient and less costly. The cost of Plan Mode includes both analysis and execution.
6. Review Diffs Before Merging
After a Background Agent completes its task, do not merge automatically. Use
git diff main...feature/agent-branch to review every change. Agent diffs
are generally clean and well-organized, but human review remains essential before
integration.
Plan Mode vs Other AI Planning Approaches
Plan Mode is not the only approach to AI-assisted planning, but it offers some distinctive characteristics compared to alternatives.
The most common alternative approach is manually writing a technical specification in a document and then giving it to the agent as context. This works, but requires much more time and does not take advantage of the agent's ability to autonomously analyze the codebase to identify relevant files.
GitHub Copilot Workspace, launched in 2024, offers a feature similar to Plan Mode integrated into GitHub Issues. Copilot analyzes the issue, generates a plan and can open PRs automatically. Cursor's advantage is direct integration with the editor: the plan is generated and executed in the same environment, with full visibility on the code and local project structure.
Conclusions
Plan Mode and Background Agents represent a qualitative leap in how developers can collaborate with AI. It is not just about speeding up work: it is about changing the type of work you can delegate.
With Plan Mode, complex features that previously required iterative Agent Mode and much supervision become structured processes with an approved plan before execution. The quality of generated code improves because the agent starts from a deep understanding of the problem, not from a generic prompt.
With Background Agents, parallelism is no longer a privilege of large companies with numerous teams. A single developer can orchestrate eight agents working simultaneously, multiplying their own productivity in a way that would be unthinkable with traditional sequential development.
The combination of both features - an accurate plan executed by coordinated parallel agents - is probably the most advanced workflow available today in a commercial IDE. It requires practice and a learning curve, but for developers who invest in mastering it, the return is substantial.
Next Steps in the Series
- Next: Cursor Hooks: Automate Your Workflow - How to automate pre and post agent execution actions
- Previous article: Agent Mode: Modify the Codebase with a Single Command - Complete guide to Agent Mode and its capabilities
- Related article: Cursor Rules: Configure AI for Your Project - How rules guide Plan Mode and agents
Connections with Other Series
- MCP and Cursor: Background Agents can use MCP tools to access databases and external APIs during execution. See the MCP Series (ID 64-77) for details.
- Vibe Coding: Plan Mode and the "spec-first" approach connect directly to the principles of vibe coding. See the Vibe Coding Series for a complementary perspective.
- Modern Angular: In the Angular workflow with Cursor, Plan Mode is ideal for scaffolding complete modules. See Angular Workflow with Cursor (ID 297).