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.

Subagents is an experimental feature. Behavior may change in future releases.

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

1. Open Cline Settings

   Click the gear icon in the Cline panel.

2. Navigate to Features

   Select the Features section in settings.

3. Toggle Subagents on

   Under the Agent section, enable the Subagents toggle.

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:

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 in parallel.

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.

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.

Auto-approve behavior

Subagents follow the Read project files auto-approve permission. If you have “Read project files” enabled in Auto Approve, subagent launches are auto-approved automatically.

In 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

Onboarding to an unfamiliar project

Ask subagents to map out the architecture, key entry points, and data flow in parallel instead of exploring one file at a time.

Investigating cross-cutting concerns

Have separate subagents trace authentication, logging, and error handling simultaneously rather than serially.

Pre-edit research

Before making changes, gather context from related files so the main agent can make informed edits without exhausting 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.

Related

• Auto Approve — Subagent launches follow the “Read project files” permission
• Deep Planning — Thorough pre-implementation codebase investigation
• Memory Bank — Persistent project context that subagents can draw on
• Task Management — Understanding context windows and how to manage them