Multi-Agent Orchestration with Subagents

When a single Claude Code session is not enough, subagents let you distribute work across multiple specialized agents that operate in parallel. Each subagent gets its own context window, tools, and configuration, making it possible to tackle complex projects where different parts require different expertise or need to progress simultaneously.

What You Will Learn

• What subagents are and how they differ from a single session
• How Claude Code launches and manages subagents internally
• Worktree isolation for safe parallel development
• How to coordinate results from multiple agents
• Practical patterns for multi-agent workflows

---

What Are Subagents?

A subagent is a separate Claude Code instance spawned by the main agent (or by you) to handle a specific subtask. Each subagent has:

• Its own context window: It does not share the parent's conversation history, so it starts fresh with only the information you provide
• Customizable tools: You can restrict or expand which tools a subagent can access
• A separate system prompt: Tailored instructions for its specific task
• Independent execution: It runs in parallel with the parent and other subagents

Think of subagents like delegating tasks to team members. You give each one a clear brief, the tools they need, and let them work independently. When they finish, you collect and integrate their results.

The Agent Tool

Internally, Claude Code uses the Agent tool to spawn subagents. When you give Claude a complex task, it may decide to launch subagents automatically. For example, if you ask Claude to "add authentication to the frontend and build the API endpoints," it might spawn one subagent for the frontend work and another for the API work.

You can also explicitly request subagent usage:

> "Use separate subagents to work on the following in parallel:
>  1. Add input validation to all API routes in src/api/
>  2. Write unit tests for the UserService class
>  3. Update the README with the new API documentation"

Each subagent receives a focused prompt and operates independently. The parent agent collects results and handles any integration work.

Subagent Configuration

Subagents support extensive configuration through frontmatter fields:

# Key frontmatter fields for subagents
description: "What this subagent does"
prompt: "Detailed instructions for the subagent"
tools: ["Read", "Edit", "Bash", "Grep", "Glob"]
disallowedTools: ["Bash(rm:*)"]
model: "claude-sonnet-4-6"
permissionMode: "auto"
maxTurns: 25
isolation: true

Key configuration options:

• model: Choose a different model for cost optimization. Use Sonnet for routine tasks, Opus for complex reasoning
• tools: Restrict available tools to only what the subagent needs
• disallowedTools: Explicitly block dangerous operations
• maxTurns: Limit how long a subagent can run to control costs
• isolation: When true, the subagent works in an isolated environment
• mcpServers: Give subagents access to specific MCP servers for specialized tool access

Worktree Isolation

One of the most powerful patterns for parallel development is git worktree isolation. When multiple agents edit the same repository simultaneously, they can create merge conflicts. Worktrees solve this by giving each agent its own working directory with its own branch.

# Create worktrees for parallel agent work
git worktree add ../project-auth feature/auth
git worktree add ../project-tests feature/tests
git worktree add ../project-docs feature/docs

Each subagent operates in its own worktree, making commits to its own branch. After all agents finish, you merge the branches:

# Merge results back
git checkout main
git merge feature/auth
git merge feature/tests
git merge feature/docs

This pattern is especially powerful for monorepos where different agents can work on different packages without interference.

Worktree Workflow in Practice

Here is a complete workflow for parallel feature development:

# Terminal 1: Launch main orchestrator
claude

> "I need three features built in parallel:
>  1. User profile page (src/pages/profile/)
>  2. Notification system (src/services/notifications/)
>  3. Admin dashboard (src/pages/admin/)
>
>  Create git worktrees for each and use subagents to build them in parallel.
>  Each agent should run tests for their area before finishing."

Claude creates the worktrees, spawns subagents, and coordinates the work. Each subagent operates in isolation, reducing the risk of conflicts.

Built-In Agent Types

Claude Code includes several built-in agent types optimized for common tasks:

• Explore: Specialized for reading and understanding code without making changes. Uses only read-only tools (Read, Grep, Glob, Bash for non-destructive commands)
• Plan: Creates detailed implementation plans without executing them. Useful as a first step before unleashing an execution agent
• General-purpose: The default agent type with full tool access

You can reference these in your workflows:

> "Use an Explore agent to analyze the authentication flow in src/auth/,
>  then use a Plan agent to design the refactoring approach,
>  then execute the plan."

Coordinating Multi-Agent Results

The orchestrating agent (parent) is responsible for integrating results from subagents. Common coordination patterns include:

Sequential Pipeline

One agent's output feeds into the next:

Agent 1 (Explore): Analyze codebase → Report
Agent 2 (Plan): Read report → Create plan
Agent 3 (Execute): Read plan → Implement changes

Parallel Fan-Out, Serial Fan-In

Multiple agents work in parallel, then a coordinator merges:

                    ┌── Agent A: Frontend ──┐
Orchestrator ──────├── Agent B: Backend  ──├── Orchestrator: Merge & Test
                    └── Agent C: Tests   ──┘

Hierarchical Delegation

A parent agent delegates to child agents, which may delegate further:

Main Agent
├── Frontend Agent
│   ├── Component Agent
│   └── Style Agent
└── Backend Agent
    ├── API Agent
    └── Database Agent

Cost and Performance Considerations

Subagents consume tokens independently. A few guidelines:

• Use cheaper models for routine tasks: Sonnet for formatting, linting, test writing. Opus for architecture decisions and complex refactoring
• Set maxTurns: Prevent runaway agents from consuming unlimited tokens
• Limit tool access: Fewer tools means less context consumption per turn
• Be specific in prompts: Vague prompts lead to more exploration turns and higher costs

// Cost-optimized subagent for simple tasks
\{
  "model": "claude-sonnet-4-6",
  "maxTurns": 10,
  "tools": ["Read", "Edit", "Grep"]
\}

Real-World Example: Full-Stack Feature

Here is how you might orchestrate a full-stack feature implementation:

> "Build a user notifications system:
>
>  Subagent 1 - Database (use Explore + Plan first):
>  - Design the notifications table schema
>  - Create the Supabase migration file
>
>  Subagent 2 - Backend API:
>  - Create CRUD endpoints for notifications at /api/notifications/
>  - Include pagination and read/unread filtering
>
>  Subagent 3 - Frontend:
>  - Build NotificationBell component with dropdown
>  - Add NotificationList page at /notifications
>  - Connect to the API endpoints
>
>  Subagent 4 - Tests:
>  - Write API tests for all notification endpoints
>  - Write component tests for the notification UI
>
>  Use worktree isolation. Each agent should work on its own branch.
>  After all complete, merge and run the full test suite."

---

Key Takeaways

• Subagents are independent Claude Code instances with their own context, tools, and configuration
• Use worktree isolation to prevent merge conflicts when multiple agents edit the same repo
• Built-in agent types (Explore, Plan, General-purpose) are optimized for different phases of work
• Configure subagents with appropriate models and maxTurns to control costs
• The parent agent coordinates results through sequential, parallel, or hierarchical patterns
• Always have the orchestrating agent run a final integration test after merging subagent work