Home / Glossary / Sub-Agents

Definition

Sub-Agents

Sub-agents are parallel child processes spawned by a main AI coding agent to handle independent parts of a complex task simultaneously. Instead of processing everything sequentially, the main agent delegates sub-tasks to specialized child agents that run in parallel and report results back to the parent.

How sub-agents work

When a main agent encounters a task with multiple independent parts, it can spawn sub-agents to handle them in parallel. For example, if you ask "refactor the authentication, payment, and notification modules to use the new error handling pattern," the main agent might spawn three sub-agents—one for each module. Each sub-agent reads the relevant files, makes changes, and runs tests independently. The main agent collects results and ensures consistency across the changes.

When sub-agents are useful

  • +Large refactoring tasks that span multiple independent modules
  • +Researching different parts of a codebase simultaneously
  • +Running multiple analysis tasks (security audit, performance check, style review) in parallel
  • +Generating code for multiple independent components at once
  • +Investigating complex bugs that may have multiple root causes

Sub-agents are most effective when the sub-tasks are truly independent—they do not modify the same files or depend on each other's output. When tasks have dependencies, sequential execution by a single agent is more appropriate to avoid conflicts.

Claude Code supports sub-agents through its Task tool. The main agent can spawn child agents with specific instructions and scoped permissions, then synthesize their results into a coherent response.

Do sub-agents share context with the main agent?+
Sub-agents receive context from the main agent when they are created, but they do not share a live context window. Each sub-agent operates independently with its own context. The main agent receives their final output and synthesizes it.
How many sub-agents can run at once?+
This depends on the tool and available resources. Claude Code can run multiple sub-agents in parallel, typically 2-5 depending on the complexity of each task. The practical limit is determined by token usage and API rate limits.
Can sub-agents spawn their own sub-agents?+
In principle, yes—this creates a tree of agents. In practice, most tasks are handled well with a single level of delegation. Deep nesting adds complexity without proportional benefit for most coding tasks.
When should I avoid using sub-agents?+
Avoid sub-agents when tasks have dependencies on each other, when they would modify the same files (risking merge conflicts), or when the task is small enough that sequential processing is faster than the overhead of spawning and coordinating multiple agents.

Related terms

Agentic CodingClaude CodeCoding AgentHeadless AI Agent

Master Claude Code in days, not months

37 hands-on lessons from beginner to CI/CD automation. Module 1 is free.

START FREE →
← ALL TERMS