Claude Code Multi-Agent Capabilities: Comprehensive Reference

Last updated: 2026-02-20

Claude Code provides multiple layers of multi-agent support, from in-process subagents within a single session to fully independent agent teams coordinating across separate sessions. This reference covers every available mechanism, how they differ, and how to use them in practice.

---

Table of Contents

1. Overview of Multi-Agent Layers
2. Subagents (In-Session Delegation)
3. Agent Teams / Swarms (Cross-Session Coordination)
4. The Claude Agent SDK (Programmatic Multi-Agent)
5. Git Worktrees for Manual Parallelism
6. Community Tooling (dmux, claude-flow, etc.)
7. Comparison Matrix
8. When to Use What
9. Sources

---

1. Overview of Multi-Agent Layers

Claude Code exposes four distinct mechanisms for multi-agent work:

Layer	Scope	Communication	Token Cost	Status
Subagents	Within a single session	Report results back to caller only	Lower (summaries return to parent)	Stable
Agent Teams	Across separate sessions	Direct inter-agent messaging + shared task list	Higher (each agent is a full instance)	Experimental
Agent SDK	Programmatic (Python/TS)	You control orchestration	You control	Stable
Git Worktrees	Manual parallel sessions	None (human coordinates)	Independent sessions	Stable

---

2. Subagents (In-Session Delegation)

Subagents are specialized agent instances spawned within a single Claude Code session. They run in their own context window, execute a task, and return results to the parent agent. They cannot communicate with each other -- only with the agent that spawned them.

Key Properties

• Each subagent has its own context window (does not pollute the parent)
• Subagents cannot spawn other subagents (no nesting)
• Results are summarized back to the parent context
• Can run in foreground (blocking) or background (concurrent)
• Invoked via the Task tool

Built-in Subagents

Agent	Model	Purpose
Explore	Haiku (fast)	Read-only codebase search and analysis
Plan	Inherits	Research during plan mode
General-purpose	Inherits	Complex multi-step tasks needing full tool access

Defining Custom Subagents

File-based (recommended for teams -- check into version control):

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

CLI-based (ephemeral, useful for automation):

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

Subagent Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier (lowercase + hyphens)
description	Yes	When Claude should delegate to this subagent
tools	No	Allowed tools (inherits all if omitted)
disallowedTools	No	Tools to deny
model	No	sonnet, opus, haiku, or inherit
permissionMode	No	default, acceptEdits, dontAsk, bypassPermissions, plan
maxTurns	No	Maximum agentic turns
skills	No	Skills to preload into context
memory	No	Persistent memory scope: user, project, local
background	No	true to always run as background task
isolation	No	worktree to run in a temporary git worktree
hooks	No	Lifecycle hooks scoped to this subagent
mcpServers	No	MCP servers available to this subagent

Background Subagents

Subagents can run concurrently in the background while you continue working. Press Ctrl+B to background a running task, or set background: true in the frontmatter. Background subagents auto-deny any permissions not pre-approved at launch and cannot use MCP tools.

Parallel Research Pattern

Research the authentication, database, and API modules in parallel
using separate subagents

Claude spawns multiple subagents simultaneously, each exploring its area, then synthesizes the findings.

Persistent Memory

Subagents can maintain knowledge across sessions using the memory field:

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

Memory is stored at ~/.claude/agent-memory/<name>/ (user scope) or .claude/agent-memory/<name>/ (project scope). The subagent reads and writes a MEMORY.md file that persists across conversations.

---

3. Agent Teams / Swarms (Cross-Session Coordination)

Agent teams are Claude Code's most powerful multi-agent feature. Unlike subagents, teammates are fully independent Claude Code instances that can communicate directly with each other, not just with a central orchestrator.

Status: Experimental

Agent teams are disabled by default. Enable them:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell environment.

Architecture

Component	Role
Team Lead	The main Claude Code session that creates the team, spawns teammates, coordinates
Teammates	Separate Claude Code instances, each with its own context window
Task List	Shared list with dependency tracking, auto-unblocking, file-locked claiming
Mailbox	Direct messaging between any agents (not routed through lead)

Storage locations:

• Team config: ~/.claude/teams/{team-name}/config.json
• Task list: ~/.claude/tasks/{team-name}/

Starting a Team

Tell Claude to create one in natural language:

Create an agent team to explore this from different angles: one teammate
on UX, one on technical architecture, one playing devil's advocate.

Or be specific:

Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Display Modes

Mode	How it works	Requirements
In-process (default)	All teammates in your terminal. Shift+Down to cycle.	Any terminal
Split panes	Each teammate gets its own tmux/iTerm2 pane	tmux or iTerm2

Configure in settings:

{
  "teammateMode": "in-process"   // or "tmux" or "auto"
}

Or per-session: claude --teammate-mode in-process

Task Management

Tasks have three states: pending, in progress, completed. Tasks can have dependencies -- a pending task with unresolved deps cannot be claimed.

• Lead can assign tasks explicitly, or teammates self-claim
• File locking prevents race conditions on claims
• Dependencies auto-unblock when predecessors complete
• View tasks with Ctrl+T (in-process mode)

Inter-Agent Communication

• message: send to one specific teammate
• broadcast: send to all teammates (use sparingly -- costs scale with team size)
• Messages delivered automatically; no polling needed
• Teammates notify the lead automatically when idle

Plan Approval Gate

For risky work, require teammates to plan before implementing:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

The teammate works read-only until the lead approves the plan. Rejected plans get sent back with feedback for revision.

Delegate Mode

Press Shift+Tab to restrict the lead to coordination only (spawning, messaging, task management), preventing it from implementing tasks itself.

Quality Gates with Hooks

Hook Event	When it fires	Exit code 2 behavior
TeammateIdle	Teammate about to go idle	Send feedback, keep teammate working
TaskCompleted	Task being marked complete	Prevent completion, send feedback

Orchestration Patterns

Worker Pool (embarrassingly parallel): Leader creates tasks; workers self-assign from a shared queue.

Sequential with Handoffs (pipeline): Tasks have blockedBy dependencies controlling execution order.

Competing Solutions (design exploration): Multiple agents tackle the same problem; leader picks the best result.

Cross-Layer Coordination: Frontend, backend, and test teammates each own their layer.

Best Practices

1. Size tasks appropriately: 5-6 tasks per teammate. Too small = overhead dominates. Too large = teammates work too long without checkpoints.
2. Avoid file conflicts: Each teammate should own different files.
3. Give rich context in spawn prompts: Teammates do NOT inherit the lead's conversation history. Include project structure, conventions, and specific goals.
4. Start with research/review: Lower risk than parallel implementation.
5. Wait for teammates: Tell the lead "wait for your teammates to complete their tasks before proceeding" to prevent the lead from implementing.

Known Limitations

• No session resumption for in-process teammates (spawn fresh after /resume)
• Task status can lag (teammates may not mark completion)
• One team per session, no nested teams
• Lead is fixed for the team's lifetime
• Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty
• Permissions propagate from lead; cannot set per-teammate modes at spawn
• Shutdown is slow while teammates finish current tool calls

---

4. The Claude Agent SDK (Programmatic Multi-Agent)

The Claude Code SDK was renamed to the Claude Agent SDK in late 2025. It exposes the same tools, agent loop, and context management that power Claude Code as a library you can call from Python or TypeScript.

Installation

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Authentication: set ANTHROPIC_API_KEY, or use Bedrock/Vertex/Azure env vars.

Basic Usage

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.py",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  if ("result" in message) console.log(message.result);
}

Programmatic Subagents

Define specialized agents that the main agent can invoke via the Task tool:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review the authentication module for security issues",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Grep", "Glob", "Task"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security.",
                    prompt="Analyze code quality and suggest improvements.",
                    tools=["Read", "Glob", "Grep"],
                    model="sonnet",
                ),
                "test-runner": AgentDefinition(
                    description="Runs and analyzes test suites.",
                    prompt="Run tests and provide clear analysis of results.",
                    tools=["Bash", "Read", "Grep"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

AgentDefinition Fields

Field	Type	Required	Description
description	string	Yes	When to use this agent (Claude reads this to decide)
prompt	string	Yes	System prompt defining behavior
tools	string[]	No	Allowed tools (inherits all if omitted)
model	'sonnet' | 'opus' | 'haiku' | 'inherit'	No	Model override

Important: Subagents cannot spawn their own subagents. Do not include Task in a subagent's tools array.

Parallel Agent Execution with asyncio.gather

The SDK's async API enables running multiple agents concurrently:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def run_agent(prompt: str, tools: list[str]) -> str:
    result = ""
    async for message in query(
        prompt=prompt,
        options=ClaudeAgentOptions(allowed_tools=tools),
    ):
        if hasattr(message, "result"):
            result = message.result
    return result

async def main():
    # Run three agents in parallel
    security, performance, tests = await asyncio.gather(
        run_agent("Audit auth.py for security vulnerabilities", ["Read", "Grep", "Glob"]),
        run_agent("Profile the hot path in api.py", ["Read", "Bash", "Grep"]),
        run_agent("Run and analyze failing tests", ["Bash", "Read", "Grep"]),
    )
    print(f"Security: {security}")
    print(f"Performance: {performance}")
    print(f"Tests: {tests}")

asyncio.run(main())

Dynamic Agent Configuration

Create agents dynamically based on runtime conditions:

def create_security_agent(level: str) -> AgentDefinition:
    is_strict = level == "strict"
    return AgentDefinition(
        description="Security code reviewer",
        prompt=f"You are a {'strict' if is_strict else 'balanced'} security reviewer...",
        tools=["Read", "Grep", "Glob"],
        model="opus" if is_strict else "sonnet",
    )

Session Resumption

Capture session IDs to resume conversations with full context:

session_id = None
async for message in query(prompt="Read the authentication module", ...):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# Resume with full context
async for message in query(
    prompt="Now find all places that call it",
    options=ClaudeAgentOptions(resume=session_id),
):
    ...

SDK Capabilities Summary

Feature	Description
Built-in tools	Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
Subagents	Define specialized agents via agents parameter
Hooks	Callback functions for PreToolUse, PostToolUse, Stop, SessionStart, etc.
MCP	Connect external services (Playwright, Slack, GitHub, etc.)
Sessions	Resume, fork, maintain context across exchanges
Permissions	Fine-grained control: allowlists, denylists, per-agent restrictions
Skills	Load .claude/skills/ markdown into agent context
Plugins	Extend with custom commands, agents, MCP servers

SDK vs CLI vs Client SDK

Use Case	Best Choice
Interactive development	CLI (claude)
CI/CD pipelines	Agent SDK
Custom applications / orchestrators	Agent SDK
One-off tasks	CLI
Direct API access with your own tool loop	Client SDK (@anthropic-ai/sdk)

---

5. Git Worktrees for Manual Parallelism

Git worktrees let you run multiple independent Claude Code sessions, each with its own working directory and branch, sharing the same repository history.

Built-in Worktree Flag

# Named worktree
claude -w feature-auth
# Creates .claude/worktrees/feature-auth/ with branch worktree-feature-auth

# Auto-named
claude -w
# Creates something like .claude/worktrees/bright-running-fox/

# Second parallel session
claude -w bugfix-123

Manual Worktree Management

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a && claude

# When done
git worktree remove ../project-feature-a

Cleanup Behavior

• No changes: worktree and branch auto-removed on exit
• Changes exist: Claude prompts to keep or remove

Add .claude/worktrees/ to .gitignore.

Session Picker Integration

The /resume picker shows sessions from all worktrees in the same git repo, making it easy to switch between parallel streams.

---

6. Community Tooling

dmux (Dev Agent Multiplexer)

A tmux-based tool that manages multiple agents in isolated git worktrees.

Source: https://github.com/standardagents/dmux Website: https://dmux.ai

npm install -g dmux
cd your-project && dmux

Press n to create a new pane. dmux creates a worktree, branch, and launches your chosen agent (Claude Code, Codex, or OpenCode) automatically.

Feature	Description
Worktree isolation	Each pane has its own working copy
Multi-agent support	Claude Code, Codex, OpenCode
A/B testing	Run two agents on identical prompts side by side
AI naming	Auto-generates branch names and commit messages
Smart merging	Auto-commit, merge, cleanup in one keystroke (m)
Lifecycle hooks	Custom scripts for worktree creation and merge events

Requirements: tmux 3.0+, Node.js 18+, Git 2.20+

claude-flow

A more elaborate orchestration platform for Claude agent swarms.

Source: https://github.com/ruvnet/claude-flow

Features distributed swarm intelligence, RAG integration, and native Claude Code support via MCP protocol. Enterprise-grade architecture for complex multi-agent workflows.

Crystal

A desktop app for isolated, parallel agentic development.

Source: https://github.com/stravu/crystal

Runs multiple Claude Code and Codex sessions in parallel git worktrees with a GUI for managing and comparing approaches.

workmux

Git worktrees + tmux windows for zero-friction parallel development.

Source: https://github.com/raine/workmux

Compound Engineering Plugin

Extends agent team workflows with structured planning and review.

Source: https://github.com/EveryInc/compound-engineering-plugin

/plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin

Provides /workflows:plan (spec generation), /workflows:review (multi-specialist code review), and /workflows:compound (learning capture).

---

7. Comparison Matrix

Dimension	Subagents	Agent Teams	Agent SDK	Git Worktrees	dmux
Agent communication	To parent only	Direct between teammates	You implement	None	None
Shared state	None	Task list + mailbox	You implement	Git repo	Git repo
Context isolation	Per-subagent	Per-teammate	Per-query	Per-worktree	Per-worktree
Parallel execution	Yes (background)	Yes (native)	Yes (asyncio.gather)	Yes (manual)	Yes (tmux panes)
Model mixing	Yes	Yes	Yes	Yes	Yes
Tool restrictions	Per-subagent	Per-team (lead sets)	Per-agent	N/A	N/A
Session persistence	Within parent session	Team config files	Session IDs	Independent	Independent
Setup complexity	Low	Medium	Medium-High	Low	Low
Token overhead	Low-Medium	High	You control	Independent	Independent
Stability	Stable	Experimental	Stable	Stable	Community

---

8. When to Use What

Use Subagents when:

• You need quick, focused workers that report back
• The task produces verbose output you want out of your main context
• Tasks are independent and do not need to communicate with each other
• You want to enforce specific tool restrictions per task
• Cost efficiency matters (results summarized, not full context)

Use Agent Teams when:

• Teammates need to share findings and challenge each other
• You want competing hypotheses investigated simultaneously
• Work spans multiple layers (frontend/backend/tests) with handoff points
• You need a shared task list with dependency tracking
• The problem benefits from diverse, parallel perspectives

Use the Agent SDK when:

• You are building a product or CI/CD pipeline (not interactive dev)
• You need full programmatic control over orchestration
• You want to compose agents with external systems
• You need custom hooks, permissions, or MCP integrations
• You are running agents headlessly in production

Use Git Worktrees when:

• You want simple, manual parallelism without coordination overhead
• Each task is truly independent (no inter-task communication needed)
• You are comfortable managing branches and merges yourself
• You want zero additional token cost from coordination

Use dmux / Community Tools when:

• You want the worktree workflow automated (branch creation, agent launch, merge)
• You want to compare multiple agents (Claude vs Codex) on the same task
• You need a lightweight alternative to agent teams without the experimental flag

Do NOT use multi-agent for:

• Sequential tasks with heavy dependencies
• Same-file edits across agents
• Small, routine changes (typo fixes, single-function edits)
• Tasks where a focused single session would be faster
• When token cost is the primary constraint

---

9. Sources

Official Anthropic Documentation

• Agent Teams (Swarms) Documentation -- complete official reference for agent teams
• Create Custom Subagents -- subagent configuration, file format, and patterns
• Agent SDK Overview -- SDK architecture, installation, capabilities
• Subagents in the SDK -- programmatic subagent definition and invocation
• Common Workflows: Git Worktrees -- parallel sessions with the -w flag
• Enabling Claude Code to Work Autonomously -- background tasks and autonomous execution

Anthropic Engineering Blog

• Building Agents with the Claude Agent SDK -- architecture, context management, subagent patterns
• Effective Harnesses for Long-Running Agents -- production agent guidance

SDK Repositories

• claude-agent-sdk (TypeScript, npm)
• claude-agent-sdk-python (GitHub)
• Example Agents (GitHub)

Community Resources and Practical Guides

• Addy Osmani: Claude Code Swarms -- comprehensive practical guide to agent teams
• dmux: Dev Agent Multiplexer -- parallel agents with tmux and worktrees
• claude-flow: Agent Orchestration Platform -- distributed swarm intelligence
• Crystal: Desktop App for Parallel Agents -- GUI for managing parallel sessions
• workmux: Git Worktrees + tmux -- zero-friction parallel dev
• Compound Engineering Plugin -- structured planning for agent teams
• Claude Code Agent Teams (alexop.dev) -- from tasks to swarms
• Claude Code's Hidden Multi-Agent System (paddo.dev) -- internals exploration
• Incident.io: Shipping Faster with Claude Code and Worktrees -- real-world team usage

IDE Integrations Using the Agent SDK

• Apple Xcode + Claude Agent SDK -- Xcode 26.3 native integration
• JetBrains IDEs + Claude Agent -- AI chat with Agent SDK
• Microsoft Semantic Kernel + Claude Agent SDK -- Agent Framework integration