How to Use Subagents in Claude Code

Anthropic’s new subagent architecture for Claude Code lets you delegate specific coding tasks to specialized AI instances without polluting your primary workspace. The official subagents guide details a system designed for strict context isolation and precise model routing. This setup prevents your main conversation from being cluttered with hundreds of files during complex exploration or research tasks. You will learn how to configure the built-in agents, define custom roles, and manage the resource requirements of delegation loops.

Context Isolation and the Agent Tool

Claude Code handles delegation through the Agent tool. This replaces the Task tool found in versions prior to 2.1.63. When the main agent delegates a task, it spins up a completely isolated instance.

This separation enforces a pattern called Strict Write Discipline. The subagent operates independently and only updates the main memory index after a confirmed successful file write. Failed attempts, dead-end file searches, and compilation errors remain contained within the subagent’s temporary environment. This keeps your primary context window clean and focused strictly on validated outcomes.

Using Built-In Subagents

The installation includes three native subagents optimized for specific development phases. You invoke them directly through the terminal interface.

Subagent	Primary Use Case	Behavior Rules
Explore	Codebase search and analysis	Read-only access, prohibited from modifying files
Plan	Architectural design and task breakdown	Generates step-by-step logic and high-level structure
General-purpose	Standard coding tasks	Fallback handler for tasks lacking a specific persona

Developers commonly use the Explore agent to navigate large repositories before asking the main agent to execute changes. This mirrors complex multi-agent systems where planning, research, and execution are rigidly divided.

Configuring Custom Subagents

You can define specialized personas for recurring tasks. Custom subagents require standard Markdown files containing YAML frontmatter. You place these files either in .claude/agents/ for project-specific tools or ~/.claude/agents/ for global availability.

The configuration allows you to pin specific subagents to different models. You can route simple documentation generation to Claude 3 Haiku to minimize API spend. You can assign security audits or heavy refactoring to Claude 3 Opus or the Mythos/Capybara model. The subagent documentation provides the complete YAML schema for defining system prompts, allowed tools, and model endpoints.

Performance Limitations and Tradeoffs

Running multiple autonomous instances requires significant local resources. Production telemetry indicates that idle subagent processes can consume up to 15GB of memory. You must ensure your development environment can accommodate this overhead before executing deeply parallelized tasks.

Agent delegation also requires robust error handling. The tool call failure rate averages 16.3% during continuous operation. This makes the Strict Write Discipline critical, as failing subagents will simply terminate without corrupting the main working tree. The architecture deliberately formalizes the popular community “Ralph Loop” pattern, replacing brittle autonomous bash scripts with controlled, native fault tolerance.

Tracking Delegation Costs

Model routing combined with parallel execution accelerates API consumption. You can track this expenditure using the built-in /cost command.

The command returns a granular breakdown of your current session. It separates charges by specific model and displays the ratio of cache-hit queries to standard queries. You can use this data to monitor LLM API costs in production and determine if a specific subagent should be downgraded to a smaller model.

To test the delegation pattern, run the built-in Explore agent on your current repository to map out dependencies before writing your first custom YAML persona.