What if you could hand off a coding task to an AI agent and come back to a finished pull request? Background Agent makes that possible -- but only if you know how to use it. Here is everything you need to know.
Background Agent is fundamentally different from interactive AI coding. If you have not tried Cursor's interactive features yet, start with our Cursor Composer guide first. Understanding the architecture helps you use it effectively.
You write a natural language description of what you want done. This can range from simple ("add a loading spinner to the dashboard page") to complex ("refactor the authentication module to support OAuth2 with Google and GitHub providers, including tests"). The quality of your instructions directly determines the quality of the output.
Cursor provisions a cloud virtual machine with your codebase, dependencies, and development environment. This VM is isolated from your local machine -- nothing the agent does affects your local files until you accept the changes. The agent has access to the full development toolkit: file system, terminal, package managers, and build tools.
The agent reads your codebase, plans its approach, writes code, runs tests, fixes errors, and iterates -- all without your involvement. It can make dozens of file changes, install packages, and run your test suite. You can monitor progress in real time or ignore it entirely and check back later. The agent typically completes tasks in minutes to tens of minutes depending on complexity.
When the agent finishes, you get a diff showing all changes. You can review the code, accept or reject individual changes, request modifications, or merge everything into your working branch. This review step is critical -- treat it like reviewing a PR from a teammate, not rubber-stamping output from an infallible machine.
Background Agent is not a replacement for interactive coding. It excels in specific scenarios where async execution is an advantage. For interactive workflow optimizations, see our Cursor tips and tricks.
When you have a well-defined feature spec, Background Agent can implement the entire thing: models, controllers, views, and tests. You keep working on other tasks while it builds the feature in parallel. This is the closest thing to having a second developer on your team.
"Write comprehensive tests for all modules in /src/services" is a perfect Background Agent task. It is tedious, well-defined, and benefits from the agent being able to read the entire codebase for context. The agent can run the tests it writes and fix failures autonomously.
Migrating from one library to another, upgrading API versions, or converting JavaScript to TypeScript are all excellent Background Agent tasks. These are mechanical, high-volume changes that follow clear patterns -- exactly what an autonomous agent handles well.
Give the agent a bug report and let it trace through your codebase to find the root cause. It can read logs, follow execution paths, write reproduction tests, and propose fixes. This works especially well for bugs that require reading many files to understand the full picture.
Background Agent is powerful but not magic. Understanding its constraints helps you avoid frustration and wasted quota.
The cloud VM has limited network access. If your task requires connecting to external APIs, databases, or services that are behind a VPN or firewall, Background Agent will not be able to reach them. Tasks that depend on local environment variables or secrets may also fail unless properly configured.
Unlike interactive agent mode where you can course-correct mid-task, Background Agent runs to completion based on your initial instructions. Vague instructions like "improve the codebase" or "make it better" lead to unpredictable results. The more specific and measurable your task description, the better the outcome.
A single Background Agent task may consume the equivalent of dozens of interactive requests because the agent makes many sequential calls during autonomous execution. Heavy users can burn through their monthly fast request quota quickly. Review our Cursor AI pricing breakdown to understand quota limits. Monitor your usage and save Background Agent for tasks where the time savings justify the quota cost.
Background Agent is one piece of the modern agentic coding workflow. Read our full Cursor AI review to see how it fits alongside interactive agent mode, Claude Code, and other tools to multiply your output while maintaining code quality.
Start Learning TodayCursor Background Agent is a feature that lets you offload coding tasks to an AI agent running on a cloud VM. Instead of the agent working inside your local editor session, it spins up a remote environment with your full codebase, works through the task autonomously, and presents you with the results as a branch or diff when it is done. You can continue working on other things -- or close your laptop entirely -- while the agent handles the task in the background.
Regular Cursor agent mode runs in your current editor session. It uses your local machine, blocks your workspace while it works, and requires you to watch and approve changes. Background Agent runs on a cloud VM separate from your local environment. It does not block your editor, does not consume your local resources, and can run for much longer without attention. Think of it as the difference between pair programming (agent mode) and delegating a task to a teammate (Background Agent).
Background Agent excels at well-specified, self-contained tasks. Adding a new API endpoint with tests, refactoring a module to use a new pattern, implementing a UI component from a design spec, writing comprehensive tests for an existing module, or migrating code from one library to another. The common thread is tasks where you can write a clear description of the desired outcome and the agent can verify its own work by running tests or type-checking.
Be specific and provide context. Instead of "add authentication," write "Add JWT-based authentication to the Express API in /src/api using the jsonwebtoken library. Add login and register endpoints, middleware for protected routes, and tests for each endpoint." Include the relevant file paths, libraries to use, patterns to follow, and acceptance criteria. The more concrete your instructions, the better the output. Think of it like writing a detailed ticket for a junior developer.
Background Agent usage is included in Cursor Pro and Business plans but consumes your fast request quota more aggressively than interactive usage because the agent makes many sequential requests during a single task. Heavy Background Agent users may hit their quota limits faster. Cursor may introduce dedicated pricing for Background Agent compute as the feature matures. Check Cursor pricing docs for the latest details on quota consumption and limits.
Both solve a similar problem: async AI coding tasks. Copilot Workspace is tightly integrated with GitHub issues and PRs -- you start from an issue and it generates a plan and implementation. Background Agent is more flexible -- you describe any task in natural language and it executes in a full development environment. Copilot Workspace focuses on the GitHub workflow; Background Agent focuses on the coding itself. The quality of output depends heavily on how well you specify the task for both tools.