Claude Code Parallel Tasks

Claude Code provides multiple mechanisms for parallel task execution, allowing you to handle multiple work items simultaneously and significantly improve development efficiency. This chapter introduces three main parallelization approaches: Subagents, Agent Teams, and Git Worktree, helping you choose the most suitable method for different usage scenarios.

Parallel Tasks Overview

When faced with complex tasks, a single Claude instance may be insufficient—context becoming too long, responses slowing down, and tasks interleaving. Claude Code provides a three-tier parallelization mechanism to meet different complexity and collaboration needs:

Selection suggestions:

• For independent subtasks that simply need parallel processing → useSubagents
• For multiple agents needing to discuss and coordinate work → useAgent Teams
• For multiple tasks needing to operate on different branches of the same repository → useGit Worktree

Subagents

What are Subagents

A Subagent is an independently running Claude instance with its own context and task focus. The main Claude can create multiple Subagents, each responsible for a specific subtask:

┌─────────────────────────────────────────────────────────┐
│                    主 Claude                            │
│                    (协调者)                              │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
┌──────────┐    ┌──────────┐    ┌──────────┐
│ Agent A  │    │ Agent B  │    │ Agent C  │
│ 代码审查  │    │ 测试生成  │    │ 文档编写  │
└──────────┘    └──────────┘    └──────────┘
        │               │               │
        └───────────────┴───────────────┘
                        │
                        ▼
                 返回结果给主代理

Up to 49 Subagents can run in parallel, fully meeting most parallel processing needs.

Built-in Subagents

Claude Code comes with the following built-in Subagents:

Creating a Subagent

Method 1: Use the /agents command

Run/agentscommand, and follow the prompts to create a new Subagent:

/agents

ChooseCreate new agent, then choose a save location, describe the functionality, and let Claude generate the configuration.

Method 2: Manually create a Subagent file

Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

Subagent Configuration Fields

Controlling Subagent Capabilities

Tool restrictions

Model selection

Invoking Subagents

Method 1: Natural language

Use the test-runner subagent to fix failing tests

Method 2: @-mention

@"code-reviewer (agent)" look at the auth changes

Method 3: Command-line launch

claude --agent code-reviewer

Foreground and Background Execution

• Foreground Subagent: Blocks the main conversation until completion
• Background Subagent: Runs concurrently, press toCtrl+Bswitch

Agent Teams

What are Agent Teams

Agent Teams allows you to coordinate multiple Claude Code instances working together. Imagine simultaneously running 4 Claude sessions (A, B, C, D), where one acts as the team leader, responsible for coordinating work, assigning tasks, and integrating results. The other three members each work independently with their own context windows, while also being able to communicate directly with one another.

Subagents vs Agent Teams

In simple terms:Subagent is like an employee reporting to the boss; Agent Teams is a project group of peers collaborating equally.。

Enabling Agent Teams

Agent Teams is disabled by default. You need to add it insettings.json:

Or set the environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Requirements: Claude Code v2.1.32 or higher

Starting an Agent Team

Once enabled, describe the task and team structure in natural language:

Controlling an Agent Team

Display mode

• In-process: All teammates run in the main terminal, useShift+Downto cycle through teammates
• Split panes: Each teammate gets their own tmux/iTerm2 pane

Specifying the number of teammates and models

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

Task assignment

• The lead can explicitly assign tasks
• Teammates can self-assign unassigned, unblocked tasks
• Tasks have three states: pending, in progress, and completed

Interacting with teammates

• In-process：Shift+DownCycle through → enter a message →EnterView →EscapeInterrupt
• Split-pane: Click a teammate's pane to interact directly

Closing teammates

Ask the researcher teammate to shut down

Agent Teams Architecture

Storage location:

• Team config: ~/.claude/teams/{team-name}/config.json
• Task list: ~/.claude/tasks/{team-name}/

Git Worktree Support

Problem Background

When multiple agents work at the same time, they may "fight" each other. Imagine this scenario: you ask Agent A to refactor the database module and Agent B to fix a bug on the login page. The two tasks seem unrelated, but they both work in the same code repository and on the same branch. Agent A is modifyingutils.py, and Agent B is also modifyingutils.py. One saves one version, the other overwrites it with a different version, ultimately leading to conflicts, errors, and even data loss.

This is not an AI problem; it is a limitation of the underlying Git repository structure.

What is Git Worktree

Git Worktree is a Git feature that lets you mount multiple independent working directories on the same repository. Each working directory has its own branch, its own HEAD, and its own staging area, but they all share the same.gitdatabase (history, object storage).

Using Git Worktree

Starting from the command line

# 创建 feature-auth 分支的工作树
claude -w feature-auth

# 同时创建 tmux 会话
claude -w feature-auth --tmux

# 使用传统 tmux
claude -w feature-auth --tmux=classic

CLI parameters

Worktree creation location:<repo>/.claude/worktrees/<name>

Desktop support

In the Claude desktop app, go to the Code tab and simply check worktree mode to enable workspace mode.

Subagent + Worktree Isolation

You can have custom Subagents always run in their own worktree:

Usage Examples

Example 1: Parallel Code Review

Example 2: Parallel Research

Research the authentication, database, and API modules in parallel using separate subagents

Example 3: Investigation with Competing Hypotheses

Example 4: Multi-branch Development

# 终端 1：重构用户模块
claude -w feature/user-refactor

# 终端 2：修复登录 bug
claude -w bugfix/login-issue

# 终端 3：开发新功能
claude -w feature/new-dashboard

Example 5: Chaining Subagents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Best Practices

Subagent Best Practices

1. Stay Focused: Each Subagent should have a clear, single responsibility
2. Limit Tools: Restrict Subagent tool access based on task requirements
3. Choose Appropriate Model: Use Haiku for simple tasks, Sonnet or Opus for complex tasks
4. Use Background Execution: Use background Subagents for long-running tasks to avoid blocking the main conversation
5. Resume Subagent: When you need to continue work, ask Claude to resume the Subagent

Agent Teams Best Practices

1. Give Teammates Enough Context: Include task-specific details in the generated prompts
2. Choose Appropriate Team Size: Most workflows start with 3-5 teammates
3. Right-Size Tasks: 5-6 tasks per teammate keeps productivity high
4. Wait for Teammates to Complete: Tell the lead to wait for teammates to finish before proceeding
5. Start with Research and Review: Start with tasks that don't require writing code
6. Avoid File Conflicts: Break up work so each teammate owns a different set of files
7. Monitor and Guide: Check progress, redirect approaches that aren't working

Git Worktree Best Practices

1. One Worktree per Task: Avoid working on multiple unrelated tasks in the same worktree
2. Use tmux Management: When running multiple Claude sessions simultaneously, use tmux for easy switching
3. Clean Up Unneeded Worktrees: Delete worktrees promptly after task completion

Troubleshooting

Agent Teams FAQ

Practical Subagent Examples

Code Reviewer

Debugger

Read-only Database Query Tool