Multi-agent

Use Claude Code’s multi-agent capabilities to parallelize large tasks across multiple worker agents — with teams, worktree isolation, and background task management.

Claude Code can spawn sub-agents — separate Claude instances that work independently on sub-tasks and report back when done. This is useful for large tasks that can be broken into parallel workstreams, such as researching multiple parts of a codebase, implementing features across different modules, or running verification on different branches simultaneously.

How it works

When Claude encounters a task that benefits from parallelism, it uses the Agent tool to spawn worker agents. Each worker:

• Starts with the task description you provide
• Has access to the standard tools (file reads, shell, code search, and more)
• Runs independently and reports its result back to the coordinator
• Can be continued, redirected, or stopped while running

The coordinator (the main Claude session) launches workers, synthesizes their results, and communicates with you. You see workers appear in the UI as they are launched and complete.

When to use multi-agent

Multi-agent mode is most effective when:

• The task has distinct, independent sub-tasks (researching two unrelated modules, writing tests for multiple services)
• You are working with a large codebase where parallel investigation is faster
• You want parallel implementation with separate verification

It is less useful for tasks that are inherently sequential (each step depends on the last).

Triggering parallel work

You can trigger multi-agent work with plain language:

> Research the auth module and the payment module at the same time.
  I need to understand both before I can make a change.

> Write unit tests for all three services in src/services/ in parallel.

> Investigate the bug from two angles at once: one agent looks at the
  database layer, the other looks at the API handler.

Claude will determine whether to launch multiple agents and, if so, will send multiple Agent tool calls in a single message to start them concurrently.

/tasks — view and manage background tasks

Run /tasks to see all running and completed background agents in the current session.

> /tasks

This shows each agent’s name, description, current status (running, completed, failed), and the results of completed agents.

/tasks has the alias /bashes for historical reasons — both commands open the same task management view.

Teams

For larger parallel workloads, Claude can create a team — a group of named agents that share a task list and coordinate with each other.

When you ask Claude to tackle a complex multi-step project, it may create a team automatically. You can also request one explicitly:

> Use a team to build the full-stack feature. I want separate agents
  for the API, the frontend component, and the test suite.

Teams work as follows:

1. Claude creates a team with a shared task list
2. It spawns teammate agents, each with a name and role
3. Teammates claim tasks from the shared list, complete them, and check for new work
4. Teammates communicate with the coordinator and with each other via messages
5. When all tasks are done, the coordinator shuts down the team

Team configs and task lists are stored in ~/.claude/teams/ and ~/.claude/tasks/ respectively.

You don’t need to manage the team yourself. Claude handles creating agents, assigning tasks, and shutting the team down when the work is complete. You can monitor progress in /tasks.

Worktree mode — isolated git branches

For tasks that require parallel changes to the codebase without conflicts, Claude supports git worktree isolation. When a worker runs with isolation: "worktree", it gets its own copy of the repository in a temporary git worktree on a separate branch.

This is useful when you want multiple agents to make independent changes (for example, two different refactors) without interfering with each other.

> Implement the two alternative approaches we discussed in separate branches
  so I can compare them.

Claude will spawn workers in isolated worktrees. If a worker makes no changes, the worktree is cleaned up automatically. If it does make changes, the worktree path and branch name are returned so you can inspect and merge the results.

Monitoring progress and results

While agents are running, Claude narrates their status. You can also ask directly:

> How are the workers doing?

When a worker finishes, its result is delivered back to the coordinator as a notification. Claude summarizes the findings and either continues the next phase of work or reports back to you.

To stop a worker that’s heading in the wrong direction:

> Stop the agent working on the JWT refactor — I changed my mind.
  Keep sessions-based auth and just fix the null pointer instead.

Claude will stop the running worker and redirect the work.

Example: parallel test generation

Here is a realistic example of using multi-agent to write tests across multiple modules in parallel:

1. Ask for parallel work

   > Write unit tests for all four modules in src/services/ at the same time.
     Each module should have its own test file in tests/services/.
   
2. Claude launches workers

   Claude spawns one worker per module, each with a specific description and task:

   • “Write tests for UserService”
   • “Write tests for OrderService”
   • “Write tests for PaymentService”
   • “Write tests for NotificationService”

   All four start in parallel.

3. Monitor in /tasks

   > /tasks
   

   You’ll see each worker listed with its current status. Workers complete independently as they finish their test files.

4. Review the results

   As each worker completes, Claude summarizes what tests were written. When all four finish, Claude gives you a summary across all modules.

   All four test suites are written. Coverage includes happy paths,
   null inputs, and error conditions for each service. Run:
   
     npm test -- tests/services/
   
   to verify everything passes.
   

Coordinator mode

For advanced use cases, you can launch Claude Code in dedicated coordinator mode by setting the CLAUDE_CODE_COORDINATOR_MODE=1 environment variable. In this mode, Claude’s role is exclusively to orchestrate workers — it delegates all file reads, edits, and shell commands to sub-agents rather than doing them itself.

CLAUDE_CODE_COORDINATOR_MODE=1 claude

Coordinator mode is best suited for large, well-defined projects where you want Claude to focus on planning and delegation rather than direct execution. Workers in coordinator mode have access to the standard tools plus any connected MCP servers.