Using Background Agents in Cursor for Automation

Cursor 1.0 introduced Background Agents - a powerful feature that allows AI agents to run tasks in the background without blocking your IDE. This guide covers how to set up, manage, and leverage background agents for maximum productivity.

What are Background Agents?

Background Agents enable:

• Long-running tasks that continue while you work on other things
• Parallel processing of multiple independent tasks
• Async operations like tests, builds, and analysis
• Scheduled tasks that run at specific times

Prerequisites

• Cursor version 1.0 or newer
• Pro or higher plan (background agents may require paid tier)
• Projects with tasks that can run independently

Starting a Background Agent

Method 1: Context Menu

1. Open Composer (Cmd/Ctrl + I)
2. Type your task description
3. Click the ... menu (More Actions)
4. Select Run in Background

Method 2: Command

@background Analyze the entire codebase for security vulnerabilities and report findings.

Method 3: Keyboard Shortcut

1. Compose your task
2. Press Cmd/Ctrl + Shift + B (if configured)
3. Agent starts in background

Background Agent Use Cases

1. Codebase Analysis

[Background] Scan the entire codebase and:
1. Find all TODO comments
2. Identify deprecated API usage
3. List files without test coverage
4. Detect potential memory leaks
5. Report code duplication

Deliver a summary report when complete.

2. Test Execution

[Background] Run the full test suite:
1. Execute all unit tests
2. Run integration tests
3. Generate coverage report
4. Save results to test-results/

Notify me when complete with pass/fail summary.

3. Documentation Generation

[Background] Generate API documentation:
1. Scan src/ for all public functions/classes
2. Create JSDoc/docstring where missing
3. Generate markdown docs in docs/api/
4. Create a navigation index

Use the existing style from src/utils/helpers.ts.

4. Refactoring Large Codebases

[Background] Refactor error handling:
1. Find all try/catch blocks
2. Standardize error messages
3. Add structured error logging
4. Create custom error classes

Apply changes across the entire codebase.

Managing Background Agents

View Active Agents

1. Open the Background Agents panel:

   • View > Appearance > Show Background Agents
   • Or use sidebar icon

2. See all running agents with:

   • Task description
   • Start time
   • Current status
   • Progress indicator

Agent States

State	Description	Action
Running	Agent is actively working	Monitor progress
Paused	Agent was manually paused	Resume or cancel
Completed	Task finished successfully	View results
Failed	Task encountered an error	Review logs
Cancelled	Task was stopped by user	Restart if needed

Controlling Agents

# Pause an agent
cursor agent:pause <agent-id>

# Resume an agent
cursor agent:resume <agent-id>

# Cancel an agent
cursor agent:cancel <agent-id>

# View agent logs
cursor agent:logs <agent-id>

Agent Output and Results

Result Types

1. File Changes: Agent modified files

   • Review in Source Control panel
   • See diff before committing

2. Reports: Generated summaries

   • Saved to specified location
   • Or shown in notification panel

3. Notifications: Status updates

   • Desktop notifications when complete
   • Badge on Cursor icon

Accessing Results

When a background agent completes:

1. Notification appears (if enabled)
2. Badge shows on Cursor dock/taskbar
3. Results panel opens automatically
4. Files changed appear in Source Control

Best Practices

Task Granularity

Break large tasks into smaller background agents:

# Good: Specific, independent tasks
[Background] Refactor auth module error handling
[Background] Refactor payment module error handling
[Background] Refactor notification module error handling

# Less ideal: One giant task
[Background] Refactor all error handling in the entire app

Resource Management

Limit concurrent background agents:

# Maximum recommended concurrent agents
- 2-3 for CPU-intensive tasks (refactoring, analysis)
- 5+ for I/O-bound tasks (documentation, reporting)

Checkpointing

For long tasks, use checkpoints:

[Background] Migrate database schema:
1. Create backup
2. Run migration scripts
3. Verify data integrity
4. Generate rollback script

Save progress after each step.
If interrupted, resume from last checkpoint.

Monitoring and Logs

View Agent Logs

1. Open Background Agents panel
2. Click on a completed agent
3. View full execution log
4. See timestamps and actions

Log Structure

[2026-06-25 10:00:00] Agent started: "Codebase security scan"
[2026-06-25 10:00:05] Reading: src/auth/login.ts
[2026-06-25 10:00:10] Reading: src/auth/register.ts
[2026-06-25 10:00:15] Analysis complete: 3 vulnerabilities found
[2026-06-25 10:00:20] Writing report: security-report.md
[2026-06-25 10:00:25] Agent completed successfully

Model Selection for Background Agents

Different models suit different background tasks:

Task Type	Recommended Model	Why
Code analysis	Claude 3.5 Sonnet	Thorough, accurate
Refactoring	GPT-4o	Fast, reliable
Documentation	Gemini 1.5 Pro	Long context
Testing	Claude 3.5 Sonnet	Good edge case detection
Security audit	Claude 3 Opus	Deep analysis

Configure default model in Settings:

{
  "backgroundAgents": {
    "defaultModel": "claude-3-5-sonnet",
    "maxConcurrent": 3,
    "autoNotify": true
  }
}

Troubleshooting

Issue	Solution
Agent won't start	Check plan limits; may need upgrade
Agent disappears	Check Background Agents panel for errors
Results not saved	Specify output path in task description
Agent hangs	Cancel and restart; may be waiting for input
High CPU usage	Reduce concurrent agents; use lighter models

Example: Complete Background Workflow

# Morning: Start analysis
[Background] Analyze technical debt in the codebase.
Generate a prioritized list of refactoring tasks.

# While agent runs, continue coding...

# Agent completes
[Notification] "Analysis complete: 12 refactoring opportunities found"

# Review results
Open: analysis-results/refactoring-tasks.md

# Start refactoring in background
[Background] Implement top 3 refactoring tasks from the analysis.

# Continue other work...

# Review changes when convenient
Check Source Control panel for diff

Related Resources

• Cursor Agent Mode Masterclass
• MCP Multi-Agent Workflows
• Handling Large Projects with Cursor