Claude Code Multi-Agent Coordination: Build AI Teams That Ship (2026)

Sync Subagents: The Blocking Pattern

Sync subagents are the simplest multi-agent pattern. The parent agent spawns a child agent and blocks - completely pausing its own execution - until the child returns a result. This is the default behavior when you ask Claude Code to delegate a task to a subagent without specifying otherwise.

When you tell Claude Code something like "run the test suite and fix any failures," the lead agent may spawn a sync subagent to execute the tests, wait for the results, then decide what to do next based on the output. The parent agent's context remains untouched while the child works. When the child finishes, the parent receives a structured result and continues its own task with full awareness of what happened.

When to use sync subagents:

• Tasks where the parent genuinely cannot proceed without the child's output
• Test execution before deciding on fixes
• Linting a file before committing it
• Running a build to verify compilation before moving to the next module
• Any workflow where step N depends on the result of step N-1

When not to use sync subagents:

• Tasks that could run in parallel. If you have three independent modules to implement, spawning them as sync subagents means each one runs sequentially - tripling the wall-clock time for no benefit. Use async agents or teammates instead.

Sync subagents also have an automatic background transition. If a sync subagent runs longer than a configured threshold, it transitions to background execution automatically. This prevents a single slow child from locking the parent indefinitely. The parent gets notified when the background task completes and can resume processing the result.

Async Agents: Background Execution

Async agents return immediately after spawning. The parent agent continues its own work without waiting for the child to finish. When the async agent completes, the parent receives a notification with the result. This is the pattern you want for parallel work.

Suppose you need to implement a new API endpoint, write tests for it, and update the documentation. With async agents, the lead agent spawns three background workers - one for the endpoint, one for tests, one for docs - and all three run simultaneously. Each agent works in its own isolated git worktree (more on this below), so there are no file conflicts. When all three finish, the lead agent reviews and merges the results.

The practical speedup is significant. Three tasks that take 60 seconds each run in 60 seconds total with async agents instead of 180 seconds with sync subagents. For development workflows involving multiple independent files or modules, this is the pattern that delivers the most visible productivity gain.

When to use async agents:

• Independent tasks with no data dependencies
• Implementing separate components in parallel
• Running a code reviewer agent alongside a test runner agent
• Any situation where multiple pieces of work can proceed without waiting for each other

Git Worktree Isolation: How Agents Avoid Conflicts

The most critical infrastructure enabling multi-agent coordination is git worktree isolation. Every agent that Claude Code spawns gets its own git worktree - a separate working directory that shares the same .git history as your main repository but has a completely independent set of working files.

This solves the fundamental problem of parallel AI coding: if two agents edit the same file simultaneously in the same directory, you get corrupted state. With worktree isolation, Agent A edits src/api/routes.ts in /tmp/worktree-a/src/api/routes.ts while Agent B edits the same file in /tmp/worktree-b/src/api/routes.ts. Both agents see the full repository history and can read any existing file, but their writes are isolated.

Worktree isolation has several practical implications that affect how you structure multi-agent tasks:

• Shared history, isolated state: All worktrees share the same .git directory. An agent in worktree B can see commits made by Agent A if Agent A commits first. But uncommitted changes in one worktree are invisible to all other worktrees.
• Automatic cleanup: If an agent finishes without making any changes, its worktree is cleaned up automatically. No manual garbage collection of temporary directories.
• Branch management: Each worktree can operate on a different branch. The lead agent manages the merge strategy after all child agents complete.
• Merge resolution: When agents working in parallel modify overlapping files, the lead agent handles merge conflicts during the integration step. This is not automatic - the lead agent applies its judgment to resolve conflicts based on the intent of each child agent's changes.

If you have worked with structured data tools where multiple transformations need to happen without interfering, the worktree pattern follows the same principle: isolate side effects, merge results explicitly.

Fork Subagents: Cache-Optimized Delegation

Fork subagents are a performance optimization for a specific scenario: when you want a child agent to inherit the parent's system prompt and initial context so that the API request prefix is cache-identical. Here is why this matters.

Claude's API caches prompt prefixes. If two requests share an identical prefix - same system prompt, same initial messages - the second request reuses the cached KV computation from the first, reducing latency and cost. Fork subagents exploit this by inheriting the parent agent's full system prompt, creating a cache-identical prefix that hits the warm cache on the API side.

In practice, this means fork subagents start faster and cost less per token than agents spawned with independent system prompts. The tradeoff is that fork subagents carry the parent's full context, which may include information irrelevant to the child's specific task. For narrowly-scoped tasks where context efficiency matters more than cache optimization, a regular sync or async agent with a tailored prompt may produce better results.

Recursive fork guard: Fork subagents include a built-in recursion guard that prevents infinite nesting. A forked agent cannot fork another agent that forks another agent indefinitely. The system enforces a maximum nesting depth. This is a safety mechanism that prevents runaway agent spawning from consuming unbounded resources.

When to use fork subagents:

• When you need to delegate a subtask that benefits from the parent's full context - reviewing code that the parent has already analyzed, running a validation step that needs the same architectural understanding, or splitting a large task into phases where each phase needs awareness of the overall plan.

Agent Teams: The Experimental Frontier

Agent teams are the most powerful coordination pattern available in Claude Code, enabled through the experimental flag CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. While sync/async subagents follow a strict parent-child hierarchy, agent teams create a flat coordination structure where multiple named agents work independently with their own context windows, their own worktrees, and the ability to communicate directly with each other.

The architecture works like this:

• One lead agent coordinates the overall task and delegates work to teammates
• Multiple teammates each operate in their own context window and git worktree
• Direct communication between any two agents via the SendMessage tool, routed by agent name
• Independent execution - each teammate works on their assigned subtask without blocking others

The key difference from async subagents is the communication model. Async subagents report back to the parent when done. Teammates can message each other at any point during execution. This enables coordination patterns that are impossible with pure parent-child hierarchies - for example, the documentation agent asking the API implementation agent about the shape of a response type while both are still working.

Named Agents and Message Routing

Agent teams use a named agent registry to enable targeted communication. When a teammate is spawned, it registers a human-readable name (like "test-runner" or "api-implementer") that maps to an internal agent ID. Any agent in the team can then use SendMessage with the target agent's name to deliver a message directly.

This naming system supports ongoing collaboration. An agent named "code-reviewer" can receive messages from the lead agent asking it to review specific files, from the "test-runner" agent reporting failures that suggest code issues, or from the "api-implementer" agent asking for a quick review of a tricky function before committing. The communication graph is fully connected - any agent can message any other agent by name.

Practical Agent Team Configuration

To enable agent teams, set the environment variable before launching Claude Code:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Once enabled, the lead agent gains the ability to spawn named teammates and route messages between them. A typical team for a feature implementation might look like this:

• Lead agent: Breaks down the feature, assigns subtasks, reviews and merges results
• "implementer": Writes the core feature code in an isolated worktree
• "test-writer": Writes comprehensive tests based on the feature spec, running in parallel
• "reviewer": Reviews code from both the implementer and test-writer, sending feedback via SendMessage

The lead agent orchestrates the sequence: implementer and test-writer start simultaneously, reviewer begins once initial code is committed, and the lead merges all worktrees when the team signals completion.

MCP Server Requirements for Agents

Agents in Claude Code can declare dependencies on specific MCP (Model Context Protocol) servers. This is particularly relevant for agents that need access to external tools - a database query server, a deployment API, a documentation search tool, or any other MCP-compatible service.

When an agent declares a required MCP server, the system checks whether that server is available before the agent begins execution. If the server is pending (starting up, not yet connected), the system waits up to 30 seconds, polling every 500 milliseconds, for the server to become available. If the server does not become available within the timeout, the agent receives an error rather than silently proceeding without the required tool.

This dependency declaration mechanism is important for reliable multi-agent workflows. Consider a team where the "implementer" agent needs access to a database schema MCP server and the "test-writer" agent needs access to a test execution MCP server. Each agent declares its requirements, and the system ensures the right servers are available to the right agents before work begins. Without this, agents would fail mid-execution when they try to invoke a tool that is not available - wasting context window tokens and wall-clock time on work that cannot complete.

For developers who use MCP servers extensively - and if you are building with tools like Google's A2A protocol alongside Claude Code, you likely are - the server requirement system ensures that multi-agent coordination does not break because of missing tool dependencies.

Remote Agents: Separate CCR Environments

Remote agents run in entirely separate Claude Code Runner (CCR) environments. Unlike local subagents that share the same machine and file system (with worktree isolation), remote agents operate on separate infrastructure with their own compute resources, file systems, and network contexts.

Remote agents are designed for scenarios where task isolation goes beyond file-level separation. Running untrusted code, executing long-running builds that should not consume local resources, or performing operations that require different system dependencies (like a different Node.js version or a specific database setup) are all cases where remote agents provide value over local subagents.

The coordination model for remote agents follows the same pattern as async agents: the parent spawns the remote agent, continues working, and receives a notification when the remote agent completes. The key difference is that the remote agent's environment is fully independent - it does not share the local .git directory, worktrees, or file system. Results must be explicitly transferred back, typically through git commits pushed to a shared remote repository.

Building a Practical Multi-Agent Workflow

Let us build a concrete example: implementing a new feature with automated code review, testing, and documentation - all running in parallel.