What are Sub-Agents in Claude Code
Sub-agents in Claude Code are specialized AI assistants that handle specific tasks in parallel while the main agent coordinates the overall workflow. They enable efficient development through two distinct approaches: manual sub-agents for explicit control and custom agents for automatic delegation.
How Sub-Agents Transform Development
Sub-agents shift Claude Code from sequential task execution to parallel processing, where multiple agents work simultaneously on different aspects of your project. When I need comprehensive code analysis, multiple sub-agents can simultaneously examine different components while the delegating agent coordinates their findings into actionable insights.
The Two Sub-Agent Approaches
Manual Sub-Agents represent the original approach using the Task tool for explicit parallel processing. You maintain direct control by specifying exactly which operations should be delegated to which sub-agents. These agents inherit the main system prompt and use the same tool selection, with configuration through task description only. This approach excels for simple parallel operations, one-off analysis tasks, and situations where you want predictable behavior without configuration overhead.
Custom Agents provide automatic delegation and specialized expertise through isolated contexts that don't inherit the main system prompt. Configured via YAML frontmatter with custom system prompts, tool selection, and specified models, these portable agents activate automatically based on task requirements. They are configured once and reused across multiple projects, making them ideal for repeated specialized work.
Key Technical Differences: Manual sub-agents inherit the main system prompt and tool selection with task-only configuration, while custom agents use isolated system prompts, custom tool selection, specified models (Haiku, Sonnet, Opus), and YAML frontmatter configuration for maximum portability and specialization.
Decision Framework for Sub-Agent Usage
Manual sub-agents work best for straightforward parallel operations where you want explicit control, excelling at file operations, searches, and basic analysis with no setup overhead. Custom agents excel for automatic delegation and specialization needed repeatedly across projects, offering isolated contexts and reusable configurations.
You can combine both approaches within the same workflow using manual sub-agents for basic operations while custom agents handle specialized tasks automatically. This flexibility allows sophisticated workflows that leverage both explicit control and intelligent automation.
Performance Benefits
Sub-agents deliver measurable performance improvements through parallel execution:
- Parallel execution eliminates waiting periods - Multiple tasks initiate simultaneously instead of one-by-one
- Significant efficiency gains for comprehensive feature implementation and large-scale code analysis
- Focused coordination - Main agent handles high-level coordination while specialized agents manage domain expertise
Practical Impact
From a practical development perspective, sub-agents enable workflows that would be impractical with sequential operation:
- Routine comprehensive analysis - Security analysis, multi-perspective code reviews, and parallel research become standard practice
- Superior division of labor - More thorough analysis and implementation compared to single agent approaches
- Fundamentally improved work quality - Enhanced scope and depth of development work
- Computational efficiency for complex modern development workflows
- Scalable workflow design that adapts to project complexity and requirements
Start with manual sub-agents for immediate parallel processing benefits, then gradually build custom agents for repeatedly needed expertise. Document successful patterns in your project's CLAUDE.md to establish consistent sub-agent workflows across your development team.
See Also: Sub-Agents|Task Agent Tools|Custom Agents|Agent Engineering