> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cline/cline/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

> Spawn parallel research agents to explore your codebase without consuming the main agent's context window.

Subagents let Cline launch focused research agents that run in parallel. Each subagent gets its own prompt and context window, explores the codebase independently, and returns a detailed report to the main agent. The main agent's context stays clean while broad information is gathered fast.

<Tip>
  Subagents is an experimental feature. Behavior may change in future releases.
</Tip>

## How it works

When Cline uses the `use_subagents` tool, it launches independent agents simultaneously. Each subagent:

* Receives its own prompt describing what to investigate
* Runs with a separate context window and token budget
* Can read files, search code, list directories, run read-only commands, and use skills
* Cannot edit files, use the browser, access MCP servers, or spawn nested subagents
* Returns a result focused on the most relevant file paths for the main agent to read next

Subagent costs (tokens and API spend) are tracked separately per subagent and rolled into the task's total cost. You can see per-subagent stats — tool calls, tokens, and cost — in the chat UI as they run.

## Enabling subagents

<Steps>
  <Step title="Open Cline Settings">
    Click the gear icon in the Cline panel.
  </Step>

  <Step title="Navigate to Features">
    Select the **Features** section in settings.
  </Step>

  <Step title="Toggle Subagents on">
    Under the **Agent** section, enable the **Subagents** toggle.
  </Step>
</Steps>

This setting applies across all editors (VS Code, JetBrains, CLI).

## Using subagents

Cline does not automatically decide to use subagents. You need to ask for them in your prompt. When the feature is enabled and you describe a task that benefits from parallel exploration, Cline will use the `use_subagents` tool.

**Example prompts:**

```text theme={null}
Use subagents to explore how authentication works and where the database models are defined.
```

```text theme={null}
Spin up subagents to investigate the API routes, the test setup, and the deployment config in parallel.
```

```text theme={null}
I'm new to this codebase. Use subagents to map out the main entry points, the routing layer, and the data access patterns.
```

Each subagent prompt should describe a focused research question. Cline runs them in parallel and synthesizes the results. You can also run a single subagent when the task is small enough that parallel discovery would add unnecessary overhead.

## What subagents can do

Subagents are read-only research agents. Here is what they have access to:

| Tool                         | Purpose                                                            |
| ---------------------------- | ------------------------------------------------------------------ |
| `read_file`                  | Read file contents                                                 |
| `list_files`                 | List directory contents                                            |
| `search_files`               | Regex search across files                                          |
| `list_code_definition_names` | List top-level classes, functions, and methods                     |
| `execute_command`            | Run read-only commands (`ls`, `grep`, `git log`, `git diff`, etc.) |
| `use_skill`                  | Load and activate skills                                           |

Subagents cannot write files, apply patches, use the browser, access MCP servers, or perform web searches. They also cannot spawn their own subagents.

<Note>
  Commands run by subagents execute in the background and are restricted to read-only operations. Subagents will not run commands that modify files or system state. They also benefit from command pipelines to narrow output before reading files — for example, `rg ... | sort | uniq`.
</Note>

## Auto-approve behavior

Subagents follow the **Read project files** auto-approve permission. If you have "Read project files" enabled in [Auto Approve](/features/auto-approve), subagent launches are auto-approved automatically.

In [YOLO mode](/features/auto-approve#yolo-mode), subagents are always auto-approved.

If auto-approve is off, Cline will ask for your approval before launching subagents and will show you the prompts it plans to send.

## When to use subagents

<CardGroup cols={2}>
  <Card title="Onboarding to an unfamiliar project" icon="map">
    Ask subagents to map out the architecture, key entry points, and data flow in parallel instead of exploring one file at a time.
  </Card>

  <Card title="Investigating cross-cutting concerns" icon="arrows-split-up-and-left">
    Have separate subagents trace authentication, logging, and error handling simultaneously rather than serially.
  </Card>

  <Card title="Pre-edit research" icon="magnifying-glass">
    Before making changes, gather context from related files so the main agent can make informed edits without exhausting its context window.
  </Card>

  <Card title="Large codebases" icon="database">
    When reading many files sequentially would consume too much of the main agent's context, subagents let you explore broadly without that tradeoff.
  </Card>
</CardGroup>

<Note>
  For small, focused tasks where you already know which files to look at, subagents add unnecessary overhead. Just ask Cline directly.
</Note>

## Related

* [Auto Approve](/features/auto-approve) — Subagent launches follow the "Read project files" permission
* [Deep Planning](/features/deep-planning) — Thorough pre-implementation codebase investigation
* [Memory Bank](/features/memory-bank) — Persistent project context that subagents can draw on
* [Task Management](/core-workflows/task-management) — Understanding context windows and how to manage them