Subagents

Subagents are specialized AI assistants that Cursor's agent can delegate tasks to. Each subagent operates in its own context window, handles specific types of work, and returns its result to the parent agent. Use subagents to break down complex tasks, do work in parallel, and preserve context in the main conversation.

You can use subagents in the editor, CLI, and Cloud Agents.

How subagents work

When Agent encounters a complex task, it can launch a subagent automatically. The subagent receives a prompt with all necessary context, works autonomously, and returns a final message with its results.

Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents don't have access to prior conversation history.

Foreground vs background

Subagents run in one of two modes:

Built-in subagents

Cursor includes three built-in subagents that handle context-heavy operations automatically. These subagents were designed based on analysis of agent conversations where context window limits were hit.

Why these subagents exist

These three operations share common traits: they generate noisy intermediate output, benefit from specialized prompts and tools, and can consume significant context. Running them as subagents solves several problems:

• Context isolation — Intermediate output stays in the subagent. The parent only sees the final summary.
• Model flexibility — The explore subagent uses a faster model by default. This enables running 10 parallel searches in the time a single main-agent search would take.
• Specialized configuration — Each subagent has prompts and tool access tuned for its specific task.
• Cost efficiency — Faster models cost less. Isolating token-heavy work in subagents with appropriate model choices reduces overall cost.

You don't need to configure these subagents. Agent uses them automatically when appropriate.

When to use subagents

Quick start

Agent automatically uses subagents when appropriate. You can also create a custom subagent by asking Agent:

For more control, create custom subagents manually in your project or user directory.

Custom subagents

Define custom subagents to encode specialized knowledge, enforce team standards, or automate repetitive workflows.

File locations

Project subagents take precedence when names conflict. When multiple locations contain subagents with the same name, .cursor/ takes precedence over .claude/ or .codex/.

File format

Each subagent is a markdown file with YAML frontmatter:

---name: security-auditordescription: Security specialist. Use when implementing auth, payments, or handling sensitive data.model: inheritreadonly: true---You are a security expert auditing code for vulnerabilities.When invoked:1. Identify security-sensitive code paths2. Check for common vulnerabilities (injection, XSS, auth bypass)3. Verify secrets are not hardcoded4. Review input validation and sanitizationReport findings by severity:- Critical (must fix before deploy)- High (fix soon)- Medium (address when possible)

Configuration fields

Model configuration

The model field controls which model a subagent uses. There are two options:

Choose inherit when the subagent needs the same reasoning power as the parent. Use a specific model ID when you need a particular model's capabilities regardless of what the parent uses.

Model parameters

Append square brackets to a model ID to set per-model options like speed, reasoning effort, and context window. Write options as id=value pairs, and separate multiple options with commas.

Available options depend on the model, and use the same id=value pairs as the SDK's model parameters.

---name: plannerdescription: Plans complex changes before implementation.model: claude-opus-5[effort=high]---Break the task into a clear, ordered implementation plan.

When the configured model won't be used

Cursor honors the model field in your subagent frontmatter unless one of these conditions applies:

• Team admin restrictions — Your organization's admin has blocked the specified model.
• Legacy Max Mode setting — On a legacy request-based plan, the model requires Max Mode and you don't have it enabled.
• Plan limitations — The model isn't available on your current plan.

In these cases, Cursor falls back to a compatible model. If you're seeing unexpected model behavior, check your plan and model settings.

---name: code-reviewerdescription: Reviews code for correctness and style.model: inherit---Review the code changes for bugs, style issues, and edge cases.

---name: search-agentdescription: Searches the codebase for relevant files and symbols.model: inherit---Search the codebase and return relevant file paths and code snippets.

---name: reasoning-agentdescription: Handles complex architectural decisions.model: gpt-5.6-sol---Analyze the architecture and recommend changes with detailed reasoning.

Using subagents

Automatic delegation

Agent proactively delegates tasks based on:

• The task complexity and scope
• Custom subagent descriptions in your project
• Current context and available tools

Include phrases like "use proactively" or "always use for" in your description field to encourage automatic delegation.

Explicit invocation

Request a specific subagent by using the /name syntax in your prompt:

> /verifier confirm the auth flow is complete> /debugger investigate this error> /security-auditor review the payment module

You can also invoke subagents by mentioning them naturally:

> Use the verifier subagent to confirm the auth flow is complete> Have the debugger subagent investigate this error> Run the security-auditor subagent on the payment module

Parallel execution

Launch multiple subagents concurrently for maximum throughput:

> Review the API changes and update the documentation in parallel

Agent sends multiple Task tool calls in a single message, so subagents run simultaneously.

Cloud subagents

From a local agent session, you can hand off work to a cloud subagent that runs on its own VM and branch. Your local workspace stays clean and responsive while long-running or parallel work happens in the cloud. The parent agent keeps running locally or in the cloud without interruption. Cloud subagents run from the Agents Window in the Cursor desktop app.

Start a cloud subagent with /in-cloud

Type /in-cloud and the next task you submit runs as a cloud subagent. It spins up its own VM and branch to work on the task.

This is useful for isolating long-running or parallel work, such as fixing CI, investigating an issue, or exploring a codebase while you keep working locally.

Babysit a PR with /babysit

Ask a cloud subagent to babysit a pull request with /babysit or by clicking the quick-action pill. The cloud agent iterates remotely to prepare the PR for merge without tying up your local session.

Cloud subagents use the environment configured for your repo and follow the same model and capability rules as other Cloud Agents. Because they run on a cloud VM, their MCP servers come from your team's configuration at cursor.com/agents, not from your local session.

Resuming subagents

Subagents can be resumed to continue previous conversations. This is useful for long-running tasks that span multiple invocations.

Each subagent execution returns an agent ID. Pass this ID to resume the subagent with full context preserved:

> Resume agent abc123 and analyze the remaining test failures

Common patterns

Verification agent

A verification agent independently validates whether claimed work was actually completed. This addresses a common issue where AI marks tasks as done but implementations are incomplete or broken.

---name: verifierdescription: Validates completed work. Use after tasks are marked done to confirm implementations are functional.---You are a skeptical validator. Your job is to verify that work claimed as complete actually works.When invoked:1. Identify what was claimed to be completed2. Check that the implementation exists and is functional3. Run relevant tests or verification steps4. Look for edge cases that may have been missedBe thorough and skeptical. Report:- What was verified and passed- What was claimed but incomplete or broken- Specific issues that need to be addressedDo not accept claims at face value. Test everything.

This pattern is useful for:

• Validating that features work end-to-end before marking tickets complete
• Catching partially implemented functionality
• Ensuring tests actually pass (not just that test files exist)

Orchestrator pattern

For complex workflows, a parent agent can coordinate multiple specialist subagents in sequence:

1. Planner analyzes requirements and creates a technical plan
2. Implementer builds the feature based on the plan
3. Verifier confirms the implementation matches requirements

Each handoff includes structured output so the next agent has clear context.

Example subagents

Debugger

---name: debuggerdescription: Debugging specialist for errors and test failures. Use when encountering issues.---You are an expert debugger specializing in root cause analysis.When invoked:1. Capture error message and stack trace2. Identify reproduction steps3. Isolate the failure location4. Implement minimal fix5. Verify solution worksFor each issue, provide:- Root cause explanation- Evidence supporting the diagnosis- Specific code fix- Testing approachFocus on fixing the underlying issue, not symptoms.

Test runner

---name: test-runnerdescription: Test automation expert. Use proactively to run tests and fix failures.---You are a test automation expert.When you see code changes, proactively run appropriate tests.If tests fail:1. Analyze the failure output2. Identify the root cause3. Fix the issue while preserving test intent4. Re-run to verifyReport test results with:- Number of tests passed/failed- Summary of any failures- Changes made to fix issues

Best practices

• Write focused subagents — Each subagent should have a single, clear responsibility. Avoid generic "helper" agents.
• Invest in descriptions — The description field determines when Agent delegates to your subagent. Spend time refining it. Test by making prompts and checking if the right subagent gets triggered.
• Keep prompts concise — Long, rambling prompts dilute focus. Be specific and direct.
• Add subagents to version control — Check .cursor/agents/ into your repository so the team benefits.
• Start with Agent-generated agents — Let Agent help you draft the initial configuration, then customize.
• Use hooks for file output — If you need subagents to produce structured output files, consider using hooks to process and save their results consistently.

Anti-patterns to avoid

• Vague descriptions — "Use for general tasks" gives Agent no signal about when to delegate. Be specific: "Use when implementing authentication flows with OAuth providers."
• Overly long prompts — A 2,000-word prompt doesn't make a subagent smarter. It makes it slower and harder to maintain.
• Duplicating slash commands — If a task is single-purpose and doesn't need context isolation, use a skill or command instead.
• Too many subagents — Start with 2-3 focused subagents. Add more only when you have clear, distinct use cases.

Managing subagents

Creating subagents

The easiest way to create a subagent is to ask Agent to create one for you:

You can also create subagents manually by adding markdown files to .cursor/agents/ (project) or ~/.cursor/agents/ (user).

Viewing subagents

Agent includes all custom subagents in its available tools. You can see which subagents are configured by checking the .cursor/agents/ directory in your project.

Performance and cost

Subagents have trade-offs. Understanding them helps you decide when to use them.

Token and cost considerations

• Subagents consume tokens independently — Each subagent has its own context window and token usage. Running five subagents in parallel uses roughly five times the tokens of a single agent.
• Evaluate the overhead — For quick, simple tasks, the main agent is often faster. Subagents shine for complex, long-running, or parallel work.
• Subagents can be slower — The benefit is context isolation, not speed. A subagent doing a simple task may be slower than the main agent because it starts fresh.

FAQ