Multi-Agent Architectures

Single agents hit a ceiling. When tasks require parallel execution, specialized expertise, or cross-domain coordination, you need multiple agents working together.

Claude Code supports two distinct approaches: Custom Subagents for isolated, specialized tasks and Agent Teams for fully parallel swarm orchestration. With the release of Claude Opus 4.6 — which plans more carefully, sustains agentic tasks for longer, and operates more reliably in larger codebases — multi-agent workflows are more powerful than ever.

Custom Subagents (The Specialist)

Subagents are specialized Claude instances that run within your current session but with their own isolated context window. They execute a focused task and return a summary to the parent — keeping your main conversation clean.

Why Subagents?

Built-in Subagents

Claude Code ships with subagents you can use immediately:

Creating Custom Subagents

Define subagents as markdown files. Claude Code looks in two locations:

• Global: ~/.claude/agents/ — available in every project
• Project-local: .claude/agents/ — scoped to one codebase

Agent File Structure

Each .md file uses YAML frontmatter to define the agent's identity:

1---
2name: security-audit
3description: Reviews code for vulnerabilities before committing.
4model: sonnet
5tools:
6  - Read
7  - Grep
8  - Glob
9---
10 
11You are a Senior Application Security Engineer. When reviewing code:
12 
131. Check for SQL injection, XSS, and command injection risks
142. Flag hardcoded credentials or API keys
153. Verify proper input validation and sanitization
164. Identify improper error handling that leaks information
17 
18Report issues with severity levels: **High**, **Medium**, **Low**.
19Include the file path and line number for each finding.

Frontmatter Reference

Practical Examples

Documentation Writer — generates docs without touching code:

1---
2name: doc-writer
3description: Generates documentation by reading code. Read-only.
4model: haiku
5tools:
6  - Read
7  - Grep
8  - Glob
9---
10 
11You are a technical writer. Read the specified code and generate:
12 
131. A concise summary of what the module does
142. Public API documentation with parameters and return types
153. Usage examples
16 
17Write in clear, jargon-free language. Target an intermediate developer audience.

Test Strategist — plans tests without running them:

1---
2name: test-strategist
3description: Analyzes code and designs comprehensive test plans.
4model: sonnet
5tools:
6  - Read
7  - Grep
8  - Glob
9---
10 
11You are a QA engineer. Analyze the specified code and produce:
12 
131. A list of test cases covering happy paths, edge cases, and error scenarios
142. Suggested test data and fixtures
153. Integration test boundaries
16 
17Do NOT write test code. Focus on what to test and why.

Invoking Subagents

Once defined, use subagents naturally in conversation:

> Use the security-audit agent to review the changes in src/auth/
> Have the doc-writer agent document the API in src/lib/api.ts
> Ask the test-strategist to plan tests for the checkout flow

Claude Code will spawn the subagent, run it with the specified tools and context, and return a summary to your main session.

Agent Teams (The Swarm)

Agent Teams, shipped as a research preview alongside Claude Opus 4.6, go far beyond subagents. Instead of a parent-child relationship, teams are fully independent Claude Code instances that work in parallel, message each other directly, and coordinate through a shared task list with dependency tracking.

Enabling Agent Teams

Add the flag to your settings.json for persistent enablement:

1{
2  "env": {
3    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
4  }
5}

Or set it in your shell for a single session:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Architecture

An agent team has four components:

How Teams Differ from Subagents

Starting a Team

Tell Claude to create a team and describe the structure you want in natural language. Claude spawns teammates and coordinates work based on your prompt.

I'm designing a CLI tool that helps developers track TODO comments
across their codebase. Create an agent team to explore this from
different angles: one teammate on UX, one on technical architecture,
one playing devil's advocate.

You can also specify models for teammates:

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

The Team Workflow

Display Modes

The default is "auto" — split panes if you're inside tmux, in-process otherwise. Override in settings.json:

{
  "teammateMode": "in-process"
}

Or per-session:

claude --teammate-mode in-process

Delegate Mode

By default, the Lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode restricts the Lead to coordination-only: spawning, messaging, shutting down teammates, and managing tasks.

Press Shift+Tab to toggle delegate mode after starting a team.

This is useful when you want the Lead to focus entirely on orchestration — breaking down work, assigning tasks, and synthesizing results — without touching code directly.

Requiring Plan Approval

For risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the Lead approves:

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

When a teammate finishes planning, it sends a plan approval request to the Lead. The Lead reviews and either approves (teammate begins implementation) or rejects with feedback (teammate revises and resubmits).

Influence the Lead's judgment with criteria:

Only approve plans that include test coverage.
Reject plans that modify the database schema.

Talking to Teammates Directly

Each teammate is a full, independent Claude Code session. You can message any teammate without going through the Lead:

• In-process mode: Shift+Up/Down to select, type to message. Press Enter to view a session, Escape to interrupt. Press Ctrl+T to toggle the task list.
• Split-pane mode: Click into a teammate's pane to interact directly.

Quality Gates with Hooks

Use hooks to enforce rules when teammates finish work:

• TeammateIdle: Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.
• TaskCompleted: Runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

Cleaning Up

When you're done, ask the Lead to clean up:

Clean up the team

This removes shared team resources. The Lead checks for active teammates and fails if any are still running — shut them down first:

Ask the researcher teammate to shut down

Known Limitations

Be aware of these current constraints:

• No session resumption: /resume and /rewind don't restore in-process teammates. After resuming, tell the Lead to spawn new teammates.
• Task status can lag: Teammates sometimes fail to mark tasks as completed, blocking dependents. Check manually if a task appears stuck.
• One team per session: Clean up the current team before starting a new one.
• No nested teams: Teammates cannot spawn their own teams. Only the Lead manages the team.
• Lead is fixed: The session that creates the team is the Lead for its lifetime.
• Permissions set at spawn: All teammates start with the Lead's permission mode. You can change individual modes after spawning.
• Split panes require tmux or iTerm2: Not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

When to Use Which

Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.

Quick Reference

Use Case Examples

Parallel Code Review

A single reviewer gravitates toward one type of issue. Split review criteria into independent domains so security, performance, and test coverage all get thorough attention simultaneously:

1Create an agent team to review PR #142. Spawn three reviewers:
2- One focused on security implications
3- One checking performance impact
4- One validating test coverage
5Have them each review and report findings.

Each reviewer applies a different lens. The Lead synthesizes findings across all three.

Adversarial Debugging

When the root cause is unclear, a single agent finds one plausible explanation and stops looking. Making teammates explicitly adversarial fights this — each one investigates its own theory while trying to disprove the others':

1Users report the app exits after one message instead of staying
2connected. Spawn 5 agent teammates to investigate different hypotheses.
3Have them talk to each other to try to disprove each other's theories,
4like a scientific debate. Update the findings doc with whatever
5consensus emerges.

The theory that survives debate is much more likely to be the actual root cause.

Cross-Layer Feature

Teammates each own a separate layer without stepping on each other:

1Build a user notifications feature. Create a team:
2- Backend teammate: API endpoints and database schema
3- Frontend teammate: notification bell component and dropdown UI
4- Testing teammate: E2E tests for the full flow
5 
6Backend should message Frontend when the API contract is ready.
7Testing should wait until both are done.

Building Your First Subagent

Let's create a practical subagent step by step.

Example: PR Review Agent

Best Practices

Designing Subagents

1. Restrict tools to the minimum needed. A review agent doesn't need Write or Edit. Fewer tools = fewer mistakes.

2. Use haiku for simple tasks. Documentation generation and summarization don't need the most powerful model. Save cost and latency.

3. Be specific in the system prompt. Vague instructions produce vague results. Include output format, evaluation criteria, and examples.

4. Test with real tasks. Run your subagent on actual code before relying on it in workflows.

Designing Agent Teams

1. Start with research and review. If you're new to agent teams, begin with tasks that don't require writing code — reviewing a PR, researching a library, or investigating a bug. These show the value of parallel exploration without coordination challenges.

2. Give teammates enough context. Teammates load project context (CLAUDE.md, MCP servers, skills) but don't inherit the Lead's conversation history. Include task-specific details in the spawn prompt.

3. Size tasks appropriately. Too small and coordination overhead exceeds the benefit. Too large and teammates work too long without check-ins. Aim for 5-6 self-contained tasks per teammate, each producing a clear deliverable.

4. Avoid file conflicts. Two teammates editing the same file leads to overwrites. Break work so each teammate owns a different set of files.

5. Monitor and steer. Check in on progress, redirect approaches that aren't working, and synthesize findings as they come in. Letting a team run unattended too long increases wasted effort.

6. Pre-approve common operations. Teammate permission requests bubble up to the Lead, creating friction. Pre-approve common operations in your permission settings before spawning teammates.

Common Pitfalls

What's Next?