Claude Code supports multi-agent orchestration — spinning up multiple AI agents working in parallel to complete complex tasks faster than a single agent could alone.
How it works
When you ask Claude to handle a large or parallelizable task, it can:
- Break the task into independent subtasks
- Spawn sub-agents via
AgentTool for each subtask
- Each sub-agent runs independently with its own tools and context
- Results are collected and synthesized by the parent agent
Spawning sub-agents
You don’t need to do anything special — just ask:
> Refactor all the API handler files to use async/await consistently
> Write unit tests for every function in src/utils/
> Review each module in src/services/ for security issues
Team-based workflows
For larger coordinated work, Claude can create a named team of agents:
> Create a team to migrate the entire codebase from JavaScript to TypeScript
- One agent reads files, others write changes
- A coordinator agent breaks down work and delegates
- A reviewer agent validates results from worker agents
Teams are cleaned up automatically or with TeamDeleteTool.
Coordinator mode
The coordinator/coordinatorMode.ts subsystem handles multi-agent orchestration at a higher level — managing agent lifecycles, work distribution, and result aggregation for complex swarm tasks.
Plan before execution
For large multi-agent tasks, enter plan mode first:
> Enter plan mode: describe how you'd parallelise migrating all our API tests to the new test framework
> Looks good, execute the plan
Example: parallel test generation
> Generate unit tests for every file in src/services/ — use multiple agents to do this in parallel
- List all files in
src/services/ using GlobTool
- Spawn one sub-agent per file (or group small files)
- Each agent reads its assigned file and writes a test file
- Parent agent reports completion
Limitations
- Sub-agents share your permission settings but each gets a fresh context window
- Very large swarms may hit API rate limits — Claude handles backoff automatically
- Sub-agent work is visible in the parent session’s output
Multi-agent workflows shine for tasks with many independent files (e.g., adding types to every module, generating tests, or updating imports across a large codebase).