Cursor Background Agents

Background Agents are Composer sessions that run in a separate process without blocking the editor. Start a long refactor, go work on something else, come back when the agent finishes. They were added to Cursor in late 2025 and matured through early 2026 to support multiple concurrent agents, partial-progress review, and checkpoint-based undo.

This page covers how to start a background agent, how to monitor one, when they beat interactive Composer, and the cost implications.

What Background Agents are

A Background Agent is a Composer session that:

• Runs in a background process owned by the Cursor app
• Does not tie up the Composer panel
• Continues when you switch projects or tasks
• Pauses if it needs user input
• Writes a diff when finished

The agent has the same tool set as interactive Composer: file read, write, grep, codebase search, terminal commands, web search. The difference is the execution model - the agent runs on its own and reports back, rather than round-tripping through your active window.

How to start a Background Agent

Open Composer with Cmd+I. Write your task prompt. In the toolbar above the input, there is a toggle for Interactive vs Background. Flip to Background and hit Send.

Alternatively, from an active Composer session, open the session menu (three dots) and pick "Move to background". The current session detaches and keeps running.

The agent gets a fresh name and appears in the Background Agents panel. That panel lives as an icon in the primary sidebar; click to open.

The Background Agents panel

The panel shows every agent in the workspace: running, paused, completed, failed. Each row has:

• Name and starting prompt
• Current status
• Elapsed time
• Step count
• Cost so far in premium requests

Click an agent to open its output stream. You see each tool call, each file read, each edit proposed. The stream updates live as the agent works.

Agent status meanings

An agent has one of five statuses:

• Running: actively calling the model and running tools
• Paused - needs input: waiting for you to answer a question
• Paused - needs approval: waiting for you to approve a write-y shell command
• Completed: finished and ready for review
• Failed: errored out; the error message is in the stream

Running and completed are self-explanatory. The two paused states differ in what the agent needs: a paused-needs-input agent wants text; a paused-needs-approval agent wants a yes or no on a pending tool call.

Responding to a paused agent

Click the agent to open the output stream. At the bottom you see the pending question or command.

For input questions, type an answer and hit Send. The agent resumes with your response as additional context.

For command approvals, click Approve to run, Reject to skip, or Edit and Run to modify the command first. The agent resumes either way.

Most agents pause 2-4 times over a long run. If you ignore a paused agent, it stays paused indefinitely; no timeout kicks in.

Reviewing completed work

When an agent finishes, the status flips to Completed. Click to see the summary: files changed, tests run, commands executed.

The diff review flow is the same as interactive Composer. Each file has Accept, Reject, or Reject with Feedback. Accept All is available but not recommended for long agent runs.

The agent makes changes to your working tree, not to git. Until you accept the diffs and commit, the changes are local only.

Canceling a Background Agent

Right-click an agent in the panel and pick Cancel. The agent stops at the next step boundary. Any file changes already made are kept in the working tree; you review and decide whether to accept.

Cancel is the right move when an agent drifts off task, tries the same thing three times without progress, or is running up the bill without visible work.

Multiple agents at once

You can run 2-3 agents in parallel on the same project, or across different projects. Cursor does not enforce a hard limit but performance starts to degrade past 5 concurrent agents because each one uses premium requests and the shared rate limit kicks in.

Good parallel patterns:

• One agent on a long refactor, another on a test suite gap
• One agent per package in a monorepo, all running in parallel
• One agent writing docs while another fixes bugs

Bad parallel patterns:

• Two agents editing the same file (conflicting diffs)
• Two agents running migrations on the same database
• Agents doing essentially the same task twice (wastes requests)

Use cases that fit Background Agents

Four task shapes where background mode is the right default.

First, long-running refactors. Migrating a component library, renaming an API across 50 files, moving from one date library to another. These take 10-30 minutes of agent time and would block the editor the whole way in interactive mode.

Second, test suite runs and gap coverage. "Add tests for every untested function in src/services." This is a slow, mechanical task where you do not need to supervise each step.

Third, generation-heavy work. Generating API clients from an OpenAPI spec, creating storybook stories for every component, writing SQL migrations from a Prisma schema change. The output is predictable, and the agent can grind through it while you work on something else.

Fourth, overnight or lunch-break tasks. Kick off before leaving for lunch, review on return. The wall-time cost is zero because you were not working anyway.

Cost implications

Background Agents use the same premium request pool as interactive Composer. A long-running agent can easily consume 50-100 premium requests in a single run. On Cursor Pro ($20/month with 500 fast premium requests) that is 10-20% of your monthly budget per agent run.

Watch for three cost traps:

1. Stuck loops: the agent retries the same failing step indefinitely. Cancel at 30 steps without visible progress.
2. Over-reading: the agent searches the codebase on every step instead of caching what it found. Tighter prompts with scoped file lists cut this.
3. Model mismatch: Opus runs 5x more expensive than Sonnet per request. Use Sonnet for background agents unless the task specifically needs Opus reasoning.

When interactive Composer wins

Background is not always right. Interactive Composer is better when:

• The task is short (under 5 minutes of wall time)
• You need to steer after each step
• The work is exploratory and you do not know the shape yet
• You want immediate feedback on diffs

For tasks where you would click Accept on every diff anyway, background mode saves time. For tasks where you want to review each step, interactive is the correct choice.

Comparing to Claude Code and terminal agents

Cursor Background Agents sit between interactive Composer and headless terminal agents like Claude Code.

Claude Code in headless mode (claude -p "task") runs fully non-interactive, typically from the terminal or a CI job. It is great for scripting and automation. The trade-off is that you lose Cursor's diff review UI and context provider shortcuts.

Cursor Background Agents keep the editor UI but decouple the agent from the foreground session. The result: you get the UX of interactive Composer with the scheduling benefit of a terminal agent.

For one-off tasks in an active editing session, Cursor Background Agents are the right tool. For scheduled or CI-integrated work, Claude Code headless wins. Many teams use both - Cursor for dev-time agent work, Claude Code for CI cleanup jobs.

Tips for effective background runs

Four practices that make background work reliably.

Write tighter prompts. Background agents cannot ask clarifying questions as easily as interactive ones because you may not see the question for an hour. Front-load the constraints.

Scope files up front. "Touch only files in src/services and the matching test files" keeps the agent from wandering across the codebase.

Set a done-when criterion. "Done when all tests pass and typecheck is green" gives the agent a clear exit condition. Without one, agents sometimes over-polish and rack up costs.

Commit before starting. The working tree is the agent's sandbox. If the agent makes a mess, git reset --hard is your undo button.