Cursor 3 Background Agents: An Async Coding Workflow Guide

TL;DR

Background Agents in Cursor 3 let you delegate coding tasks asynchronously — like assigning tickets to a fast junior developer who works while you focus elsewhere. This guide covers what they actually are, five workflow patterns that hold up in daily use, how to configure rules and cloud environments, where agents struggle, and the security limits to keep firm when an agent runs unattended and connects to your systems. The throughput is real, but it is only useful to the degree you can review what comes back.

Table of Contents

• What Background Agents Actually Are
• Setting Up the Agents Window
• Five Practical Workflow Patterns
• Configuration That Determines Output Quality
• Where Agents Struggle
• Security When Agents Run Unattended
• Background Agent vs Claude Code vs Copilot Agent
• Best Practices for Daily Use
• Key Takeaways
• FAQ
• Related Resources

What Background Agents Actually Are

Background Agents run tasks independently of your active editing session. Unlike inline completions or synchronous chat, they don't block your workflow — you describe a task, the agent works, and you get notified when it's done or needs input.

The mental model is delegation, not direction:

Each agent gets its own isolated environment:

• Local worktree agents run in a separate Git worktree on your machine, preventing conflicts with your working directory.
• Cloud agents run on dedicated VMs with full dev environments — they keep going after you close your laptop.
• Remote SSH agents execute on your own servers or dev machines.

The key point: agents don't just generate snippets. They clone repos, install dependencies, write code, run tests, self-correct on failures, and open pull requests. That is full-cycle work — which is exactly why the review step at the end is not optional. An agent that runs the whole loop unattended can also be confidently wrong for the whole loop.

New to AI agents? Start with our AI Agent glossary entry for foundational concepts.

Setting Up the Agents Window

The Agents Window is your control center for running agents. It presents each agent as a tab with real-time status:

You can tile agents side by side to monitor multiple tasks. Each tab shows the current step, the file-changes diff, terminal output, and (for UI tasks) browser screenshots.

Launching an agent is a matter of describing the task:

// From Cursor's command palette or chat:
// "Create a Background Agent to add input validation to the user registration form"

// The agent will:
// 1. Create a new Git worktree
// 2. Analyze the existing form code
// 3. Add validation logic with Zod schemas
// 4. Write unit tests
// 5. Run tests and fix failures
// 6. Present a diff for your review

The workflow is the same for any language — the agent identifies the relevant files, makes the change, adds tests, runs them, and submits the result for you to check.

Five Practical Workflow Patterns

These patterns come from daily use. Each fits a specific development scenario.

Pattern 1: Assign and Forget — Mechanical Refactors

The simplest pattern. Describe a refactor with an unambiguous end state and move on:

Task: "Refactor the payment service to use the Strategy pattern.
Extract each payment method (Stripe, PayPal, Apple Pay) into its own
strategy class. Maintain backward compatibility with existing tests."

Best for mechanical refactors with clear rules, style migrations (e.g., class → functional components), and predictable dependency upgrades. Use it when the desired end state is unambiguous — and still read the diff, because "unambiguous to you" is not the same as "correctly understood by the agent."

Pattern 2: Parallel Test-Coverage Sprint

Launch several agents at once, each scoped to a different module:

Each agent gets a scoped directive:

// Agent 1 task:
`Write unit tests for src/auth/.
Follow the existing patterns in src/auth/__tests__/login.test.ts.
Mock external services with MSW. Cover the error and edge cases, not just the happy path.`

Use it to raise coverage before a release — but treat the combined result as one large PR to review, not as coverage you can trust because a number went up. Tests an agent writes can pass while asserting the wrong behavior.

Pattern 3: Review Prep — Agent Pre-Reviews

Before requesting human review, have an agent analyze the PR:

Task: "Review the changes in PR #247. Flag possible:
1. Security issues (injection, XSS, auth bypass)
2. Performance regressions (N+1 queries, missing indexes)
3. Missing error handling
4. Breaking API changes
Post findings as a summary."

This surfaces obvious issues before a human reviewer spends time. Treat the output as a checklist of things to look at, not a verdict — a pre-review that says "no issues found" is not a security sign-off, and human review still happens.

Pattern 4: Worktree Isolation for Experiments

Create a fully isolated branch for speculative work:

/worktree Experiment with replacing Express with Hono for the API layer.
Migrate 3 representative endpoints. Compare request throughput.
Report results without merging.

The agent works in its own worktree; your working directory stays untouched, and if the experiment fails you discard it with zero cleanup. Use it for evaluating libraries, architectural experiments, and risky migrations you want to try before committing.

Pattern 5: Best-of-N Model Racing

Run the same task across multiple models at once and keep the best result:

/best-of-n composer, claude-sonnet, gpt-5
Implement a rate-limiter middleware using a sliding-window algorithm.
It must handle distributed scenarios with Redis.

Cursor creates a separate worktree per model. When all finish, you compare implementations side by side and merge the winner. The value is cheap parallel options plus your comparison — which model "wins" varies by task, so this replaces a guess about which model is best with evidence for this specific problem. Read each candidate before choosing; a shorter or longer diff is not automatically the better one.

Configuration That Determines Output Quality

Configuration is the difference between agents that "kind of work" and agents that consistently produce reviewable, production-quality code.

Project Rules

The rules file tells agents your project's conventions — think of it as onboarding documentation for a new contributor:

# .cursor/rules
project:
  name: "acme-api"
  language: "TypeScript"
  framework: "NestJS"
  test_runner: "Jest"

conventions:
  - "Use dependency injection via NestJS providers"
  - "All endpoints require the @Auth() decorator"
  - "Database access only through the repository pattern"
  - "Error responses use ProblemDetails (RFC 7807)"
  - "No console.log in production code — use the Logger service"

testing:
  - "Unit tests in __tests__/ adjacent to source"
  - "Integration tests in test/ at project root"
  - "Mock external APIs with nock"

Keep rules short, specific, and testable. Concrete rules ("all endpoints require @Auth()") measurably change output; vague ones ("write clean code") do nothing.

Cloud Environment Configuration

For cloud agents, declare the environment so runs are reproducible:

{
  "image": "node:20-bookworm",
  "setup": {
    "commands": ["npm ci", "npx prisma generate"]
  },
  "services": {
    "database": "postgres:16",
    "cache": "redis:7-alpine"
  },
  "secrets": ["DATABASE_URL", "STRIPE_SECRET_KEY", "JWT_SECRET"]
}

Reference secrets by name from the Secrets settings so they are injected at build time and never written into the agent's workspace or committed to the repo.

Multi-Repo Setup

Recent versions let agents operate across multiple repositories, each with its own rules:

# .cursor/multi-repo.yaml
repositories:
  - path: "./backend"
    rules: "./backend/.cursor/rules"
    language: "Python"
  - path: "./frontend"
    rules: "./frontend/.cursor/rules"
    language: "TypeScript"
  - path: "./shared-types"
    rules: null  # uses root rules
    language: "TypeScript"

# Example task spanning repos:
# "Update the User type in shared-types, then update the backend
#  serializers and frontend components to match."

Multi-repo capability and file names change between releases, so confirm the current format in Cursor's own documentation before relying on it.

Where Agents Struggle

Background Agents are useful, not magical. These limits are real:

1. Architectural decisions. Agents execute well on clearly scoped tasks but are poor at deciding whether to use microservices vs. a monolith, or event sourcing vs. CRUD. Keep strategic decisions human.
2. Large context requirements. Very large monorepos can exceed the context window. If an agent needs to hold 50+ files at once, it may miss connections — break the work into smaller units.
3. Exploratory or creative work. When the goal is vague ("make the UX feel better"), agents produce generic output. They need concrete acceptance criteria.
4. Subtle state machines. Multi-step business logic with edge cases usually needs iterative human-agent collaboration, not pure delegation.

The common thread: agents are strong at execution of a well-specified task and weak at judgment about what the task should be. Keep the judgment.

Write Verifiable Tasks

// ❌ Vague
"Make the code better"

// ✅ Specific and verifiable
"Refactor src/services/email.ts:
- Extract HTML template rendering into a TemplateService
- Add retry logic for SMTP failures (3 attempts, exponential backoff)
- Add unit tests for the retry behavior, including the exhausted-retries case
- Run existing tests to ensure no regressions"

Security When Agents Run Unattended

An agent that runs the full loop unattended and connects to your systems operates with real privileges. A few boundaries do not move, regardless of how convenient the workflow is:

• Grant the least access that does the job. A cloud agent that can clone your repo, reach your services, and open PRs is a powerful identity. Scope its credentials and environment access to the task, not to everything.
• Authentication is identity, not authorization. When an agent connects to internal systems (often via MCP), a valid token proves who is calling — not that the caller may act on a specific record. The server behind the connection must still enforce object-level and tenant-level access on every request.
• A pre-review is not a security control. An agent's "no issues found" summary flags what it noticed; it does not authorize a merge. Security-relevant changes still need human review and your normal checks.
• Tests and passing CI prove what they cover. An agent can write tests that pass while asserting the wrong thing, so a green run is evidence only for the behavior the tests actually assert.

None of these change the value of Background Agents — they define the conditions under which the value is safe to collect.

Background Agent vs Claude Code vs Copilot Agent

The right async coding tool depends on your workflow. The durable distinctions are about shape, not a leaderboard:

Specific limits and pricing change often, so treat this as a map of design shapes and verify current details at each vendor. For a repeatable way to decide on your own tasks, see How to Run Your Own Evaluation of Cursor, Claude Code, and Copilot, and for the broader landscape, the AI Coding Tools 2026 Comparison.

Best Practices for Daily Use

1. Write tasks like tickets, not chat messages. Include context, acceptance criteria, and constraints. The agent can't ask clarifying questions mid-run.

2. Start with low-stakes tasks. Don't hand your first agent a critical production hotfix. Begin with test generation, docs, or dependency upgrades, and build trust incrementally.

3. Use worktrees for anything experimental. It costs nothing to discard. Treat them like draft branches that never touch your working copy.

4. Correct output deliberately. When you review and fix something, note the convention in your rules file so the improvement persists across runs rather than being re-learned each time.

5. Batch related tasks for parallelism — up to what you can review. Four agents each covering one module beats one agent covering the whole app, but only if you can actually check four PRs.

6. Review diffs closely, don't rubber-stamp. Agents show you exactly what changed. Spend your review energy there, and never merge a multi-file change you have not understood.

7. Keep the rules file updated. As the project evolves, so should the rules. It's the single most impactful lever on output quality — effectively prompt engineering for your whole project.

Key Takeaways

• Background Agents = async delegation. Assign tasks and get results without blocking your current work.
• Five patterns cover most use cases: assign-and-forget, parallel test sprints, review prep, worktree experiments, and best-of-n racing.
• Configuration quality determines output quality. Invest in the rules file and a reproducible environment.
• Parallelism multiplies generation, not review. Scale the number of agents to what you can meaningfully check.
• Know the boundaries. Agents excel at well-scoped execution and struggle with ambiguity and architecture.
• Autonomy raises the stakes. Least-privilege access, real authorization on the server, and human review of security-relevant changes are non-negotiable.

For a deeper look at Cursor 3's design ideas, see our Cursor 3 Explained.

Related Resources

• Cursor 3 Explained: The Design Ideas Behind Agent-First IDEs
• How to Run Your Own Evaluation of Cursor, Claude Code, and Copilot
• Claude Code Agent Programming Guide
• AI Coding Tools 2026 Comparison
• Spec Coding Complete Guide
• Context Engineering Complete Guide