How It Works
When Cline uses theuse_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 that includes file paths, line numbers, and recommended files for the main agent to read next
Enabling Subagents
Subagents are disabled by default. To turn them on:- Open Cline Settings (click the gear icon in the Cline panel)
- Go to Features
- Under the Agent section, toggle Subagents on
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 mention subagents (or describe a task that benefits from parallel exploration), Cline will use theuse_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”
- “I’m new to this codebase. Use subagents to map out the main entry points, the routing layer, and the data access patterns”
Auto-Approve Behavior
Subagents follow the Read project files auto-approve permission. If you have “Read project files” enabled in Auto Approve, subagent launches will be auto-approved. In YOLO mode, subagents are always 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 |
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.
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.