Claude Code's multi-agent system lets you orchestrate multiple AI agents that work in parallel across isolated git worktrees, communicate directly with each other, and merge their results back into your codebase — all from a single terminal session. This is not a theoretical capability. It is production-ready infrastructure that ships with Claude Code today, and an experimental agent teams feature that takes coordination further. This guide covers every agent pattern available, when to use each one, and the practical configurations that make parallel AI coding work reliably.
The Core Primitive: AgentTool
Every multi-agent capability in Claude Code flows through a single abstraction called AgentTool. AgentTool is the orchestrator that spawns, manages, and routes communication between agents. It supports five distinct agent types, each optimized for different coordination patterns:
Sync subagents — blocking execution, parent waits for child to finish
Async agents — background execution, parent gets notified on completion
Fork subagents — inherit parent context for cache-identical API prefixes
Teammates — named agents with direct inter-agent message routing
Remote agents — separate Claude Code Runner (CCR) environments
Understanding which pattern fits your task is the difference between agents that coordinate smoothly and agents that block each other, duplicate work, or produce merge conflicts. Let us walk through each one in detail.
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.gitdirectory. 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 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.
Step 1: Define the Task Decomposition
The lead agent receives the feature request and breaks it into independent subtasks. The critical judgment here is identifying which tasks have data dependencies (must run sequentially) and which are independent (can run in parallel). For a typical feature:
- Core implementation: depends on nothing, can start immediately
- Test writing: depends on the interface contract (function signatures, types), not the implementation details
- Documentation: depends on the interface contract and high-level behavior description
- Code review: depends on implementation being complete
This means implementation, test writing, and documentation can all start in parallel if the lead agent first establishes the interface contract (types, function signatures, expected behavior) and shares it with all agents.
Step 2: Spawn Async Agents with Worktree Isolation
The lead agent spawns three async agents, each receiving the interface contract and their specific instructions. Each agent gets an isolated worktree. All three begin working simultaneously.
The implementer writes the feature code. The test writer writes unit and integration tests against the interface contract. The documentation writer updates API docs and adds usage examples. None of them block each other. If the test writer needs clarification about an edge case, they can send a message to the implementer via SendMessage (if agent teams are enabled) or flag it for the lead agent to resolve.
Step 3: Sequential Review and Integration
Once all three async agents complete, the lead agent spawns a sync subagent for code review. This is intentionally sequential — the reviewer needs the completed implementation and tests to provide meaningful feedback. The reviewer checks for type safety, error handling, edge cases, and consistency between the implementation and tests.
If the reviewer identifies issues, the lead agent can spawn additional async agents to fix specific problems in parallel, or handle small fixes itself. Once the review passes, the lead agent merges all worktrees into the main branch, resolving any conflicts.
Step 4: Final Verification
A final sync subagent runs the full test suite against the merged code, verifying that the parallel work integrates correctly. This is the gate before the lead agent reports the task as complete.
This entire workflow — implementation, testing, documentation, review, and verification — runs in roughly the time of the longest single task plus the sequential review and verification steps. For a feature that takes 3 minutes to implement, 2 minutes to test-write, and 1 minute to document, the parallel phase takes 3 minutes instead of 6. The sequential review and verification add another 2 minutes. Total: 5 minutes instead of 8+ minutes for fully sequential execution.
Agent Coordination Patterns That Work
After extensive use of Claude Code's multi-agent system in production codebases, several coordination patterns consistently deliver results:
The Scout-Implement-Verify Pattern
Spawn a sync "scout" agent first to analyze the codebase and produce a plan. Then spawn async agents to implement different parts of the plan in parallel. Finally, run a sync verification agent to confirm everything works together. This pattern works well for refactoring tasks, where understanding the existing code is a prerequisite for safe changes. The comparison to how you might use .
Custom LangChain/CrewAI agent frameworks require you to build the orchestration, tool access, and state management yourself. Claude Code provides this infrastructure out of the box, with git worktree isolation and the AgentTool abstraction handling the mechanics. The tradeoff is flexibility: custom frameworks let you orchestrate any model from any provider, while Claude Code's agents use Claude exclusively.
Google's A2A protocol is an open standard for inter-agent communication across different platforms and providers. Claude Code's agent teams are a closed system — all agents are Claude instances coordinated within the Claude Code runtime. A2A aims for cross-platform interoperability. These are complementary rather than competing approaches — you might use Claude Code agent teams for implementation work and A2A for broader system orchestration. See our for utilities that complement AI-assisted coding workflows, and read our
SOCIAL SHARE CARD GENERATOR