wehub-resource-sync
80 lines
4.5 KiB
Plaintext
80 lines
4.5 KiB
Plaintext
---
|
|
title: "Subagents"
|
|
sidebarTitle: "Subagents"
|
|
description: "Run parallel research agents to explore your codebase without filling the main agent's context window."
|
|
---
|
|
|
|
Subagents let Cline spawn 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. This keeps the main agent's context clean while gathering broad information 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 one:
|
|
|
|
- Gets 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, cost) in the chat UI as they run.
|
|
|
|
## Enabling Subagents
|
|
|
|
Subagents are enabled by default. Cline decides when parallel research is worth the overhead — you don't need to opt in or call them out in your prompt. To turn subagents off, disable the `use_subagents` tool in Settings → Features → Agent.
|
|
|
|
This setting applies across all editors (VS Code, JetBrains, CLI).
|
|
|
|
## Using Subagents
|
|
|
|
When subagents are enabled, Cline picks them up on its own when a task benefits from parallel exploration. You can also nudge it explicitly by asking for parallel research in your prompt.
|
|
|
|
Example prompts:
|
|
|
|
- "Use subagents to explore how authentication works and where the database models are defined"
|
|
- "Spin up subagents to investigate the API routes, the test setup, and the deployment config"
|
|
- "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 will run them in parallel and synthesize the results.
|
|
You can also run only one subagent when the task is small enough that parallel discovery would be unnecessary overhead.
|
|
|
|
## 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 will be auto-approved.
|
|
|
|
If auto-approve is off, Cline will ask for your approval before launching subagents, showing you the prompts it plans to send.
|
|
|
|
## 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.
|
|
Subagents also benefit from command pipelines and filters to narrow output quickly before reading files, for example `rg ... | sort | uniq`.
|
|
</Note>
|
|
|
|
## When to Use Subagents
|
|
|
|
Subagents work best when you need broad context from multiple areas of a codebase at once:
|
|
|
|
- **Onboarding to an unfamiliar project**: Ask subagents to map out the architecture, key entry points, and data flow in parallel.
|
|
- **Investigating cross-cutting concerns**: Have separate subagents trace authentication, logging, and error handling simultaneously.
|
|
- **Pre-edit research**: Before making changes, use subagents to gather context from related files so the main agent can make informed edits without burning through its context window.
|
|
- **Large codebases**: When reading many files sequentially would consume too much of the main agent's context, subagents let you explore broadly without that tradeoff.
|
|
|
|
For small, focused tasks where you already know which files to look at, subagents add unnecessary overhead. Just ask Cline directly.
|