Claude Code Subagents: Multi-Agent Guide

What are Claude Code subagents?

Claude Code subagents are independent agent instances that your main Claude Code session can spawn to handle tasks in parallel. Instead of doing everything sequentially in one conversation, you can delegate work to multiple agents that run simultaneously, each with its own context, tools, and working directory.

Think of it like hiring contractors. Your main session is the project manager. It breaks the work into pieces, hands each piece to a subagent, and collects the results. The subagents don't talk to each other: they report back to the orchestrator.

This is multi-agent coding in practice. Not a theoretical framework. Not a research paper concept. It's a feature you can use today to parallelize real development work.

How the Agent tool works

The core mechanism behind Claude Code subagents is the Agent tool. When Claude Code determines that a task can be broken into independent pieces, it spawns child agents using this tool.

Each subagent gets:

• Its own conversation context: separate from the parent session
• A specific task description: what it needs to accomplish
• Access to tools: Read, Write, Edit, Grep, Glob, Bash, and others
• A working directory: either the same directory or a separate worktree

The parent session waits for all subagents to complete, then synthesizes their results. You see the final output as if one agent did everything, but it happened in parallel.

Here's what the flow looks like:

Main Session
├── Subagent 1: "Update the auth middleware"
├── Subagent 2: "Write tests for the payment module"
└── Subagent 3: "Refactor the database queries"
    ↓
Results collected → Main session continues

Each subagent operates independently. If Subagent 2 fails, Subagents 1 and 3 still complete. The main session handles the failure and can retry or adjust.

Parallel execution with worktrees

When subagents modify files, you hit a problem: two agents editing the same file simultaneously creates conflicts. Claude Code solves this with git worktrees.

A worktree is a separate working directory linked to the same git repository. Each subagent gets its own worktree, so it can read and write files without interfering with other agents. When all subagents finish, the changes are merged back.

The workflow is:

1. Main session identifies parallelizable tasks
2. Claude Code creates worktrees for each subagent
3. Each subagent works in its own worktree
4. Changes are merged back to the main branch
5. Conflicts (if any) are resolved by the main session

This is the same concept as developers working on separate feature branches, but automated and happening in seconds, not days. For a deeper look at how worktrees function in Claude Code, check out our worktrees guide.

When to use subagents

Not every task needs multiple agents. Here's when parallel agents actually help:

Good use cases for Claude Code agent teams

Large refactors across independent modules. If you need to update the API layer, the frontend components, and the test suite, and none of those changes depend on each other, three subagents finish in the time one agent would take for a single module.

Research + implementation splits. One agent researches the best approach (reading docs, searching the codebase, checking patterns), while another starts scaffolding based on the likely approach. When research completes, implementation adjusts.

Multi-file test generation. Writing tests for 10 different modules is embarrassingly parallel. Each test file is independent. Ten subagents can write ten test files simultaneously.

Codebase analysis. Scanning a large codebase for security issues, performance problems, or code quality across different directories. Each agent takes a section.

When single-agent is better

Sequential tasks. If step 2 depends on step 1's output, parallelism doesn't help. You're just adding overhead.

Small changes. Spawning subagents has overhead: creating worktrees, managing context, merging results. For a quick bug fix or a small feature, a single agent is faster.

Tightly coupled code. If every file depends on every other file, parallel edits create merge nightmares. Work sequentially instead.

Context-heavy tasks. When the agent needs deep understanding of one specific area, splitting focus across multiple agents means none of them have the full picture.

Practical examples

Example 1: Adding a feature across the stack

You ask Claude Code to add a "user preferences" feature. The main session breaks it down:

• Subagent 1: Create the database migration and model
• Subagent 2: Build the API endpoints and validation
• Subagent 3: Create the frontend components and hooks

Each agent works in its own worktree. The database schema, API routes, and React components are written simultaneously. Total time: roughly what one piece would take alone.

Example 2: Codebase-wide lint fix

Your linter reports 200 issues across 50 files. Instead of one agent fixing them sequentially:

• Subagent 1: Fix issues in src/components/
• Subagent 2: Fix issues in src/api/
• Subagent 3: Fix issues in src/utils/
• Subagent 4: Fix issues in src/hooks/

Four agents, each handling a directory. What would take 20 minutes takes 5.

Example 3: Documentation generation

You need API docs for 15 endpoints. Each endpoint's documentation is independent:

• Spawn one subagent per endpoint (or group them into 3-4 agents)
• Each reads the route handler, extracts parameters, and writes the doc
• Main session compiles them into a single documentation file

Building your own agent teams

If you're using custom commands, you can design workflows that naturally leverage subagents. The key principle: decompose tasks into independent units.

A command like /refactor might instruct Claude to:

1. Identify all modules affected by the refactor
2. Group them by dependency (independent groups can be parallelized)
3. Spawn subagents for each independent group
4. Merge and verify the results

You don't need to explicitly tell Claude Code to "use subagents." Describe the task clearly, and Claude Code decides whether parallel execution makes sense. But structuring your CLAUDE.md and commands to highlight independence between modules helps Claude make better parallelization decisions.

Subagent limitations to know

Context isolation. Subagents don't share context with each other. If Agent A discovers something Agent B needs to know, that information doesn't transfer. The main session has to broker it.

Token cost. Each subagent uses its own token budget. Three subagents doing moderate work cost roughly 3x what one agent would cost for one of those tasks. You're trading money for time.

Merge complexity. When subagents modify related (but not identical) code, merges can get complex. Claude Code handles most merges automatically, but edge cases may need manual resolution.

No inter-agent communication. Subagents can't message each other mid-task. It's a fan-out/fan-in pattern, not a collaborative discussion. If your task needs agents to negotiate or iterate together, the current model doesn't support that.

FAQ

How many subagents can Claude Code run at once? Claude Code can spawn multiple subagents in parallel, typically 3-5 depending on the task complexity. The practical limit depends on your system resources and the nature of the work: more agents means more worktrees and more concurrent file operations.

Do subagents cost extra tokens compared to a single agent? Yes. Each subagent has its own context window and token usage. Running three subagents costs roughly three times the tokens of one agent doing one-third of the work. The trade-off is wall-clock time: parallel execution finishes faster even though total token spend increases.

Can I control when Claude Code uses subagents vs. working sequentially? You can influence this through how you describe tasks. Explicitly mentioning that parts are independent encourages parallel execution. Describing tasks as sequential steps encourages single-agent work. Your CLAUDE.md file and custom commands can also structure work to favor one approach over the other.

Ship faster with parallel agents

Claude Code subagents turn sequential bottlenecks into parallel workflows. The pattern is simple: identify independent tasks, let Claude Code spawn agents for each, collect the results. For complex projects with clear module boundaries, multi-agent coding cuts development time significantly.

If you want agent teams pre-configured with production-tested commands, worktree management, and orchestration patterns, Claudify ships with 9 specialist agents and the coordination logic to run them. One command to install: npx create-claudify.

Get Claudify: 21 commands, 9 agents, 1,727 skills. Installed in one command.