Permission System: 5-Layer Priority, Rule Syntax and Complete Sandbox Configuration Guide

Chapter 45: Claude Code Multi-Agent Mode: Parallel Tasks and Worktree Isolation

45.1 The Limits of Single-Agent Operation

Claude Code in single-agent mode works serially: it finishes one task before starting the next. For most everyday programming tasks, this is fast enough. But as tasks grow in scope, the limits of serial execution become apparent.

Imagine a refactoring job that requires simultaneously updating the API layer, database models, frontend components, and test files — four parts that are logically independent. A single agent processes these sequentially, while multi-agent mode can run four Claude instances at once.

Claude Code's multi-agent mode is built on two mechanisms:

• The Agent tool: allows one Claude instance to launch and coordinate another Claude instance
• Git Worktree isolation: provides an independent workspace for each parallel task, preventing file conflicts

45.2 The Agent Tool: Orchestrator and Executor Pattern

In Claude Code, the AI can use a special tool called Agent, which allows the current Claude instance (the orchestrator) to launch new Claude instances (executors) to complete subtasks.

This creates a hierarchy:

User
 └── Orchestrator Claude
      ├── Executor Claude 1: handles backend API changes
      ├── Executor Claude 2: handles database migration
      ├── Executor Claude 3: handles frontend component updates
      └── Executor Claude 4: handles test updates

Triggering Multi-Agent Mode

Describe a complex parallelizable task to Claude:

I need to migrate the project from REST API to GraphQL. This task breaks down
into several independent parts:
1. Create the GraphQL schema and resolvers
2. Update the database query layer
3. Update frontend API calls
4. Update related tests

Please use multi-agent mode to handle these tasks in parallel, using Git Worktree
to isolate each task's workspace.

Claude analyzes the task, confirms which parts can be parallelized, and then launches multiple agent instances.

The Orchestrator's Workflow

When Claude acts as the orchestrator, it:

1. Decomposes the task: breaks the large task into independently executable subtasks
2. Analyzes dependencies: identifies which subtasks have ordering dependencies and which can be parallelized
3. Assigns work: creates a separate Worktree and Agent for each parallel task
4. Aggregates results: waits for all agents to complete, reviews results, and handles conflicts
5. Integrates changes: merges each branch's modifications into the main branch

45.3 Git Worktree: Physical Isolation for Parallel Tasks

Git Worktree is a Git feature that lets you check out multiple working directories from the same repository simultaneously, with each directory on a different branch:

# Check the current worktree state
git worktree list

# Example output:
# /path/to/project          abc1234 [main]
# /path/to/project-feat-api def5678 [feature/graphql-api]
# /path/to/project-feat-db  ghi9012 [feature/graphql-db]

Each worktree has an independent working directory but shares the same .git database, which means:

• Each worktree works on its own branch without interfering with others
• Worktrees can see each other's commits (via git fetch)
• Disk space usage is minimal (Git object store is shared)

Creating a Worktree Manually

# Create and switch to a new branch in a new worktree
git worktree add ../project-graphql-api -b feature/graphql-api

# Verify the result
git worktree list

# In another terminal, navigate to the new worktree
cd ../project-graphql-api
# This directory is on the feature/graphql-api branch,
# but shares the main project's git history

Letting Claude Manage Worktrees

In a practical multi-agent workflow, you can have the orchestrator Claude handle creating and managing worktrees:

Please complete the following tasks in parallel, creating a separate Git Worktree
for each:

Task 1: graphql-schema
  Working directory: ../project-graphql-schema
  Branch: feature/graphql-schema
  Job: Create GraphQL schema files and type definitions

Task 2: graphql-resolvers
  Working directory: ../project-graphql-resolvers
  Branch: feature/graphql-resolvers
  Job: Implement GraphQL resolvers (depends on schema; start after schema is done)

Task 3: frontend-migration
  Working directory: ../project-frontend
  Branch: feature/frontend-graphql
  Job: Update frontend Apollo Client config and queries

Claude will execute:

# Orchestrator creates worktrees
git worktree add ../project-graphql-schema -b feature/graphql-schema
git worktree add ../project-frontend -b feature/frontend-graphql

# Then launch agents for each worktree
# Agent 1 works in ../project-graphql-schema
# Agent 3 works in ../project-frontend (can be parallel — no schema dependency)
# Agent 2 waits for schema to finish before starting

45.4 Dependency Management for Parallel Tasks

Not all tasks can be fully parallelized. The key technique in multi-agent mode is dependency graph analysis:

Sample task dependency graph:

[schema definition] ──────────────→ [resolver implementation]
        │                                       │
        ↓                                       ↓
[type generation]                       [integration tests]
        │
        ↓
[frontend type updates] → [frontend component updates]

In this dependency graph:

• schema definition must complete first
• resolver implementation, type generation, and frontend type updates can run in parallel after schema is done
• integration tests can only run after resolvers are done
• frontend component updates must wait for frontend type updates

Tell the orchestrator Claude about these dependencies:

The tasks have the following dependencies:
- schema must complete first
- resolvers and type generation can run in parallel after schema is done
- frontend work can start after type generation is complete
- integration tests run last

Please schedule the parallel work according to this dependency order,
maximizing parallelism.

45.5 Background Agents: Launching Async Tasks

Claude Code supports launching agents in "background mode," allowing an agent to run in the background without blocking the current conversation:

Start the following tasks in background mode — I will continue other work:

Background Task 1: Run the full test suite and generate a report
  Command: pnpm test --coverage && pnpm test:e2e
  Tell me the results when done

Background Task 2: Run dependency analysis on the entire src/ directory
  Command: npx depcheck
  Tell me about unused dependencies when done

This mode is especially useful for:

• Running long-running test suites
• Executing large-scale static analysis
• Performing codebase-wide searches and indexing

45.6 A Real Multi-Agent Case: Large-Scale Refactoring

Here is a complete multi-agent workflow example: migrating a Node.js project from JavaScript to TypeScript.

Preparation Phase: Orchestrator Analyzes the Codebase

The orchestrator Claude first analyzes the codebase:

# Analyze file structure
find src/ -name "*.js" | wc -l           # count JS files
find src/ -name "*.js" -exec ls -la {} \; # check file sizes

# Identify entry points and core modules
cat package.json | jq '.main, .scripts'

Based on the analysis, the orchestrator determines the migration strategy:

Analysis result: 47 JS files in src/, organized into 5 independent modules:
- src/api/ (12 files) — REST API routes
- src/services/ (15 files) — business logic
- src/db/ (8 files) — database layer
- src/utils/ (7 files) — utility functions
- src/middleware/ (5 files) — Express middleware

Suggested plan: migrate utils and db in parallel (independent of each other),
then migrate services and middleware in parallel,
then migrate api last (depends on all other modules).

Execution Phase: Parallel Migration

# Orchestrator creates worktrees
git worktree add ../migrate-utils -b migrate/utils
git worktree add ../migrate-db -b migrate/db

# Launch two agents to work in parallel
# Agent 1: migrate src/utils/ to TypeScript
# Agent 2: migrate src/db/ to TypeScript

Each agent works independently in its worktree.

Agent 1 (utils migration):

# Inside ../migrate-utils
cd src/utils/
# Process each file: add type annotations, rename .js to .ts, fix type errors
for file in *.js; do
  # Claude handles the migration of each file
done
pnpm tsc --noEmit  # verify no type errors
pnpm test utils    # run related tests
git add . && git commit -m "migrate: convert src/utils to TypeScript"

Agent 2 (db migration): Similar process in its own worktree.

Merge Phase: Orchestrator Integrates Results

# After both parallel tasks complete
git checkout main

# Merge utils migration
git merge migrate/utils --no-ff -m "merge: TypeScript migration for utils"

# Merge db migration
git merge migrate/db --no-ff -m "merge: TypeScript migration for db"

# Handle any conflicts manually (unlikely since they worked in separate directories)

# Clean up worktrees
git worktree remove ../migrate-utils
git worktree remove ../migrate-db

45.7 Limitations and Cautions for Worktrees

Be aware of these limitations when using Git Worktree:

Conflicts on Shared Files

Some files are not appropriate to modify simultaneously across multiple worktrees:

• package.json (dependency changes)
• CLAUDE.md (convention changes)
• Database schema files

When assigning tasks, ensure shared files are only modified by one agent.

The node_modules Problem in Node.js Projects

Installing dependencies independently in each worktree can consume significant disk space. Solutions:

# Use pnpm (supports content-addressed storage across worktrees)
pnpm install  # automatically reuses dependencies from the main directory

# Or create a symlink
ln -s ../project/node_modules ./node_modules

A Branch Cannot Exist in Two Worktrees Simultaneously

Git does not allow the same branch to be checked out in two worktrees at the same time. Ensure each parallel task uses a unique branch name.

45.8 When to Use Multi-Agent Mode

Not every task warrants multi-agent mode. Here is a decision framework:

Good candidates for multi-agent mode:

• Task can be clearly decomposed into mutually independent subtasks
• Each subtask requires at least 30 minutes of work
• Subtasks touch different code areas (minimizing file conflicts)
• You need to simultaneously explore multiple solution approaches

Poor candidates for multi-agent mode:

• Task is highly coupled; each step depends on the previous step's results
• Task is small; coordination overhead exceeds the parallelism benefit
• Work touches the same set of files (generates many conflicts)

Rule of thumb: If a task will take less than 15 minutes, serial single-agent processing is simpler and more efficient. For tasks expected to take more than 30 minutes that can be decomposed, multi-agent starts to provide real value.

Summary

Claude Code's multi-agent mode, through the combination of the Agent tool and Git Worktrees, enables automation of large-scale parallel development tasks.

Key takeaways:

• The orchestrator-executor pattern lets one Claude instance manage multiple concurrently working sub-agents
• Git Worktree provides independent filesystem isolation for each parallel task, preventing conflicts
• Dependency graph analysis is the core technique for multi-agent coordination, determining which tasks can run in parallel
• Background agent mode is ideal for long-running tasks (tests, analysis)
• Shared files (package.json, schema) should not be modified simultaneously by multiple agents
• Multi-agent mode is best suited to large decomposable tasks such as major refactors and system-level migrations