Cursor AI v3: Complete Guide to Background Agents and Subagents (2026)

Cursor AI v3 is the IDE that moved AI from a suggestion box into a full autonomous coding partner. With over 1 million active users and $100 million in annual recurring revenue reached within its first 12 months, it has become the benchmark against which every other AI-assisted development tool is measured. This guide walks you through every major feature — from zero-friction Tab completion all the way to parallel Subagents tackling large refactors — so you can build a workflow that fits your actual projects.

What Is Cursor AI v3?

Cursor is a fork of VS Code rebuilt around the idea that the editor should be agent-first. Rather than bolting a chat window onto an existing IDE, Cursor puts AI at the center of every interaction: it reads your whole codebase, understands imports and call graphs, and proposes or executes changes across multiple files simultaneously.

Version 3, released in early 2026, introduced Background Agents, Subagents, and a redesigned Composer 2.0 with Plan Mode. These additions transformed Cursor from a fast inline assistant into a system capable of running autonomous, long-horizon tasks in the background while you continue coding in the foreground.

Key numbers from the Cursor team: - More than 1 million developers use Cursor daily. - The product crossed $100 million ARR within 12 months of its public launch. - Teams report 20–40% faster feature delivery when they adopt the full Agent workflow.

Installation and Initial Setup

Download and Install

Go to cursor.com and download the installer for your platform (macOS, Windows, or Linux). The macOS build is a universal binary that runs natively on both Apple Silicon and Intel. Run the installer and open Cursor. It will detect any existing VS Code settings, keybindings, and extensions and offer to import them automatically.

Choosing a Model

On first launch you are prompted to select a default model. The two most popular choices in 2026 are:

claude-sonnet-4-5 — Anthropic's model. Excellent at reasoning through complex refactors, writing tests that actually pass, and following nuanced instructions inside .cursorrules. Recommended for agent-heavy workflows.
GPT-4o — OpenAI's multimodal flagship. Fast and well-suited for tasks that involve reading screenshots or diagrams.

You can switch models per-session from the model picker in the bottom status bar. Some teams set claude-sonnet-4-5 as the default for Agent Mode and GPT-4o for quick inline edits where raw speed matters more than deep reasoning.

Account and Billing

Cursor offers a free tier with limited monthly completions, a Pro tier at $20/month for individual developers, and Business plans for teams. API keys for the underlying models are managed by Cursor; you do not need a separate Anthropic or OpenAI account unless you want to bring your own key (BYOK), which is supported on the Business plan.

Tab Completion: The Baseline Feature

Tab completion is the first thing you notice and the one feature that requires zero prompting. Cursor observes what you are typing, infers intent from surrounding context — the function signature above, the import at the top of the file, the test below — and proposes a completion in grey text. Press Tab to accept it, Escape to dismiss.

What makes Cursor's Tab different from GitHub Copilot's original implementation is that it reads your entire codebase, not just the open file. If you have a UserService class in services/user.py and you start typing a new method in api/endpoints.py that calls it, Cursor already knows the method signatures, the data types involved, and the error handling patterns your project uses. The completion it offers is consistent with your actual code.

Tab completion is the lowest-friction entry point. Use it for: - Boilerplate (constructors, getters, test setup blocks) - Repetitive transformations (applying the same pattern to a list of fields) - Filling in obvious next steps after you have written a function signature

Do not expect Tab to handle architectural decisions. For anything beyond a few lines, move to Inline Edit or Agent Mode.

Inline Edit Mode: Highlight, Describe, Accept

Inline Edit is activated with Cmd+K (macOS) or Ctrl+K (Windows/Linux). Highlight the code you want to change, press the shortcut, type a description of the change you want, and press Enter. Cursor rewrites the highlighted block and presents the result as a colored diff — green for additions, red for deletions — directly in your editor.

You can accept the change with Cmd+Y, reject it with Cmd+N, or click individual hunks to accept partial changes.

Example workflow:

1. Highlight a 30-line function that returns raw SQL.
2. Press Cmd+K.
3. Type: "Refactor to use SQLAlchemy ORM, keep the same return shape."
4. Review the diff, accept.

Inline Edit is the right tool when: - You know exactly which block of code needs to change. - The change is self-contained (no need to touch other files). - You want to review the full diff before it lands in your repo.

The key discipline here is reviewing the diff. AI output at this level is fast and usually good, but not always right. Treat it as a first draft from a capable junior developer: read it, understand it, then accept.

Agent Mode: Autonomous Multi-File Editing

Agent Mode is where Cursor starts to feel like a second developer on your team. Activate it from the Composer panel (Cmd+I or Ctrl+I) and switch the toggle from "Chat" to "Agent". Describe what you want to build or fix in plain language. Cursor will:

Search your codebase for relevant files.
Open, read, and edit multiple files.
Run terminal commands (tests, linters, build steps) with your approval.
Iterate until the task is done or it needs clarification.

When to use Agent Mode instead of Inline Edit: - The change spans more than two files. - You need the AI to discover which files are relevant rather than specifying them yourself. - The task involves a chain of steps (write the migration, update the model, add a test, update the docs).

Agent Mode is not magic. Give it a clear, scoped task. "Add a /health endpoint to the FastAPI app, write a pytest for it, and update the OpenAPI description" will succeed. "Improve the app" will produce a random walk through your codebase.

Background Agents: Async Tasks While You Keep Coding

Background Agents are new in Cursor v3. They allow you to dispatch a task to a cloud-hosted agent and immediately return to your own work. The agent runs in a sandboxed clone of your repository, edits files, runs tests, and creates a pull request (or a local branch if you prefer). A notification appears in the status bar when it finishes.

To start a Background Agent: 1. Open the Agent panel. 2. Click "Run in Background". 3. Describe the task. 4. Choose a target branch. 5. Click "Start".

You can monitor running Background Agents from the status bar icon or from the "Agents" sidebar panel. Each agent shows its current step, elapsed time, and a live log.

Background Agents are well-suited for: - Writing a full test suite for an existing module while you build the next feature. - Migrating a legacy file to a new API while you work on unrelated code. - Running a security audit and generating a findings report.

Because Background Agents run in a cloud sandbox, they do not block your local machine and do not interfere with your local git state. Review their output as a pull request the same way you would review any branch: read the diff, run the tests, merge when satisfied.

Subagents: Parallel Execution for Large Refactors

Subagents were added to Cursor in January 2026. Where a single Agent Mode session operates sequentially — one file at a time, one step at a time — Subagents allow you to spin up multiple Claude instances in parallel, each with its own independent context window and task scope.

This is the feature that makes large-scale refactors practical. Instead of asking a single agent to rename a pattern across 200 files (which would be slow and might exceed the context window), you split the task:

Subagent 1: handles src/api/
Subagent 2: handles src/services/
Subagent 3: handles tests/

Each subagent works independently, and their outputs are reconciled into a single branch. Because each subagent has a fresh context window, there is no degradation in quality as the task grows.

How to launch Subagents: 1. Open Agent Mode. 2. Describe the overall task. 3. Click "Parallelize" — Cursor will propose a split; you can adjust the boundaries. 4. Approve and start.

Subagents report status individually in the Agents panel. You can cancel a misbehaving subagent without stopping the others.

Composer 2.0 and Plan Mode

Composer 2.0 is the redesigned multi-turn conversation interface in Cursor v3. It replaces the older Composer with a session-aware panel that maintains context across many back-and-forth turns, understands the files you have open, and can search your codebase inline during a conversation.

Plan Mode is an opt-in feature inside Composer 2.0. When you enable it, Cursor does not immediately execute changes. Instead, it produces a numbered plan — a list of files it intends to touch and what it will do to each one — and waits for your approval before executing.

Example Plan Mode output:

Plan for "Add JWT authentication to the Flask app":

1. Install flask-jwt-extended (requirements.txt)
2. Create src/auth/jwt.py — token creation and validation helpers
3. Update src/app.py — register the JWT manager
4. Update src/routes/user.py — protect /profile and /settings endpoints
5. Add tests/test_auth.py — tests for login, refresh, and protected routes
6. Update README.md — document the new Authorization header format

Approve to execute, or edit the plan before running.

Plan Mode is valuable when you are working in a production codebase where an unexpected file change could cause real damage. Review the plan, remove any steps you want to handle manually, then approve. Cursor executes only the approved steps.

MCP Server Integration

Cursor v3 supports the Model Context Protocol (MCP), which lets you connect external tools and data sources to the AI. MCP servers expose tools that Cursor's agents can call during a task.

Common MCP integrations: - GitHub MCP — agents can open issues, read PR comments, and push branches directly. - Jira MCP — reference ticket requirements without leaving the editor. - Database MCP — agents can query your development database schema and sample data to write accurate queries. - Slack MCP — surface recent discussion about a module before editing it.

To configure an MCP server, add it to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Restart Cursor after saving. The connected tools appear in the Agent panel under "Available Tools". Agents can now call them autonomously when the task requires it.

.cursorrules and CURSOR.md: Project-Specific Instructions

.cursorrules is a plain-text file you place at the root of your repository. Cursor reads it at startup and injects its contents into every AI context. Use it to encode conventions that every contributor (human or AI) should follow.

Example .cursorrules:

- This project uses Python 3.12 and SQLAlchemy 2.x ORM syntax. Never write raw SQL.
- All API endpoints must have a corresponding pytest in tests/. Name them test_<endpoint>.py.
- Error responses must use the ErrorResponse Pydantic model from src/models/errors.py.
- Do not modify alembic/versions/ directly. Generate migrations with `alembic revision --autogenerate`.
- Commit messages must follow Conventional Commits: feat:, fix:, chore:, docs:.

CURSOR.md is a Markdown file recognized by Cursor v3 as a higher-level project brief. It is a good place to describe the architecture, the tech stack, and the reasoning behind non-obvious decisions. Agents read it before starting any task, giving them context that would otherwise take dozens of back-and-forth messages to establish.

Both files are committed to the repository, so every team member gets the same AI behavior without any per-developer configuration.

Local-to-Cloud Agent Handoff

Cursor v3 supports a hybrid execution model. You start a task locally — perhaps because you want to watch the first few steps to verify the agent is on the right track — and then hand it off to a cloud Background Agent for the rest of the run.

To handoff: 1. Start Agent Mode locally. 2. Let it run for a few steps. 3. Click "Continue in Background" in the Agent panel.

Cursor snapshots the agent's current state, uploads it to the cloud sandbox, and continues from where it left off. Your local machine is free immediately. This is useful for tasks that will take 10–30 minutes: verify the approach locally, then let the cloud finish the work.

Best Practices

Build review habits from day one. Every AI output — whether a Tab completion, an Inline Edit diff, or an Agent pull request — is a draft. Read it before you accept it. The moment you start rubber-stamping AI output is the moment bugs start accumulating silently.

Follow the Tab → Inline → Agent progression. Tab for small completions. Inline Edit for targeted block changes. Agent Mode for cross-file tasks. Background Agents and Subagents for long-running or parallel work. Using the right tool for the task keeps you in control and keeps the AI focused.

Write tight .cursorrules. The more precisely you encode your project's conventions, the less you will need to correct AI output. Invest 30 minutes writing a thorough .cursorrules when you set up a new project; it pays back many times over.

Scope your Agent tasks clearly. Vague instructions produce vague results. Before you send a task to an agent, ask yourself: could I hand this to a new junior developer and expect a useful pull request within an hour? If the answer is no, break the task down further.

Treat Subagents as a parallel review panel. After a large refactor with Subagents, read each subagent's output separately before merging. Conflicts are rare because subagents are given non-overlapping scopes, but interfaces between the scopes are where errors can creep in.

Use Plan Mode in production codebases. The two seconds it takes to read and approve a plan will save you from the 20 minutes it takes to untangle an agent that touched a file it should not have.

Conclusion

Cursor AI v3 represents a genuine shift in what it means to work with an AI coding assistant. The layered feature set — Tab completion at the bottom, Subagents and Background Agents at the top — means you can adopt as much or as little automation as your workflow and your confidence level support. Start with Tab and Inline Edit. Graduate to Agent Mode once you have a solid .cursorrules in place. Then explore Background Agents and Subagents when you have tasks that are well-defined enough to run autonomously. The 20–40% productivity gains teams are reporting are real, but they come from disciplined use of the right feature at the right time — not from handing the entire codebase to an AI and hoping for the best.