How to Run Claude Code in Parallel: 5 Methods from Terminal Panes to Agent Teams

Why Run Claude Code in Parallel

A single Claude Code session reads your codebase into one context window. On a 200K-line project, that context fills up after reading 30-50 files. Ask for a refactor that touches 15 files, and the agent is already forgetting the patterns from the first file by the time it reaches the last.

Parallel sessions solve this by giving each task its own context window. The auth refactor agent does not share context with the test-writing agent. Each one focuses on fewer files, retains more detail, and produces better output.

Method 1: Terminal Panes (Simplest)

The fastest way to run multiple Claude Code sessions. Open your terminal, split it into panes, and run claude in each one. Zero setup, zero configuration. Each pane is an independent session with its own context window.

Step-by-step

# Split vertically (side by side)
# Cmd+D in iTerm2, or:
# Ctrl+B then % in tmux

# Pane 1: auth refactor
claude
> Refactor the authentication module to use JWT tokens

# Pane 2: test writing (Cmd+D to split, then run)
claude
> Write integration tests for the payment API

# Pane 3: bug fix (Cmd+D again)
claude
> Fix the race condition in the WebSocket handler

#!/bin/bash
# save as parallel-claude.sh

SESSION="claude-parallel"
tmux new-session -d -s $SESSION -c ~/myproject

# Split into 3 panes
tmux split-window -h -t $SESSION -c ~/myproject
tmux split-window -v -t $SESSION -c ~/myproject

# Send claude command to each pane
tmux send-keys -t $SESSION:0.0 "claude" Enter
tmux send-keys -t $SESSION:0.1 "claude" Enter
tmux send-keys -t $SESSION:0.2 "claude" Enter

# Attach
tmux attach -t $SESSION

Method 2: Git Worktrees (Recommended)

Git worktrees give each Claude session its own branch and its own directory on disk, while sharing the same git history. Claude Code has native support via the -w flag. Run claude -w feature-name and it creates the worktree, branches your code, and starts a session inside it. One command.

Step-by-step

# Terminal pane 1: auth feature
claude -w feature-auth
> Implement OAuth2 login with Google and GitHub providers

# Terminal pane 2: bug fix
claude -w bugfix-race-condition
> Fix the race condition in src/lib/websocket.ts

# Terminal pane 3: test coverage
claude -w tests-payment
> Add integration tests for the Stripe webhook handler

# Each session runs in its own directory:
# ~/myproject/.worktrees/feature-auth/
# ~/myproject/.worktrees/bugfix-race-condition/
# ~/myproject/.worktrees/tests-payment/

# 1. Start parallel sessions (each in its own terminal pane)
claude -w feature-auth
claude -w feature-dashboard

# 2. Each session works in isolation
#    feature-auth edits src/lib/auth.ts
#    feature-dashboard edits src/app/dashboard/page.tsx
#    No conflicts. Different branches, different directories.

# 3. When done, merge results back
cd ~/myproject
git merge feature-auth
git merge feature-dashboard

# 4. Clean up worktrees
git worktree remove .worktrees/feature-auth
git worktree remove .worktrees/feature-dashboard

# Or let Claude handle cleanup:
# claude -w feature-auth --resume  (to check on progress)

Community tools for worktree management

Several tools automate the worktree lifecycle. ccswitch manages parallel sessions with automatic worktree creation and cleanup. parallel-code gives each task its own git branch and worktree automatically. GitButler uses Claude Code's lifecycle hooks to create a new branch for every session. All of these build on the same git worktree primitive.

Method 3: Subagents (Within a Session)

Subagents run inside a single Claude Code session. The parent agent spawns child agents, each with its own context window. The children do their work and report back. You stay in one terminal, and Claude handles the parallelism internally.

This is not the same as running multiple terminals. Subagents share the parent's working directory but get isolated context. The parent coordinates results. Think of it as Claude delegating to itself.

Step-by-step

# In a single Claude Code session, give a task that benefits from parallelism:

> Refactor the API layer. Spawn separate subagents for:
  1. Migrate all REST endpoints from Express to Hono
  2. Update the OpenAPI spec to match new routes
  3. Rewrite integration tests for the new endpoints

# Claude spawns 3 subagents internally:
# - Agent 1: reads Express routes, rewrites in Hono
# - Agent 2: reads current OpenAPI spec, updates paths
# - Agent 3: reads existing tests, rewrites for new API
# Each gets its own context window. No cross-contamination.
# Parent collects results and merges them.

# You can combine subagents with worktrees for file isolation:

> Spawn a subagent in a worktree to handle the database migration.
  It should:
  1. Create a new migration file
  2. Update the schema
  3. Run the migration
  4. Verify with a test query
  Give it its own worktree so it doesn't interfere with my work.

# Claude creates a worktree, spawns a subagent inside it,
# and the subagent works independently while you continue
# in the main session.

Method 4: Agent Teams (Coordinated Sessions)

Agent Teams are the official Anthropic solution for coordinated parallel work. Unlike subagents, team members can message each other directly, share a task list with dependency tracking, and self-organize without routing everything through a lead. Each teammate runs in its own context window and optionally its own terminal pane.

Step-by-step

# Option 1: Environment variable (add to ~/.zshrc or ~/.bashrc)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Option 2: settings.json (~/.claude/settings.json)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

# Option 3: One-time for current session
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

# Start Claude Code (with agent teams enabled)
claude

# Tell it to create a team
> Create a team of 3 agents:
  - "auth-agent": implement OAuth2 with Google provider
  - "test-agent": write integration tests for the auth flow
  - "docs-agent": update the API documentation for auth endpoints
  The test-agent should wait for auth-agent to finish before
  writing tests against the new code.

# Claude creates 3 teammates. Each gets:
# - Its own context window
# - Its own terminal pane (if using tmux/iTerm2)
# - Access to a shared task list
# - Ability to message other teammates directly

# The lead agent coordinates. test-agent blocks on auth-agent.
# docs-agent works in parallel with auth-agent.

# For visual monitoring, run inside tmux first:
tmux new -s claude-team

# Then start Claude Code
claude

# Each teammate gets its own tmux pane automatically.
# You can click into any pane to interact with that agent.
# The lead stays in the original pane.

# Alternative: iTerm2 with Python API enabled
# iTerm2 > Settings > General > Magic > Enable Python API
# Teammates appear as native iTerm2 split panes.

Method 5: Docker Containers (Full Isolation)

For maximum isolation, run each Claude Code session in its own Docker container. Each container gets its own filesystem, package installations, running processes, and network stack. No possibility of cross-contamination. This is the setup used by teams running 10+ parallel agents on shared infrastructure.

Step-by-step

# Dockerfile.claude-agent
FROM node:20-slim

# Install Claude Code
RUN npm install -g @anthropic-ai/claude-code

# Install git
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

# Set up workspace
WORKDIR /workspace

# Clone from upstream on startup
ENTRYPOINT ["sh", "-c", "git clone /upstream . && claude --dangerously-skip-permissions"]

version: "3.8"

services:
  agent-auth:
    build:
      dockerfile: Dockerfile.claude-agent
    volumes:
      - ./bare-repo:/upstream:ro
      - auth-workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_INITIAL_PROMPT=Implement OAuth2 with Google provider

  agent-tests:
    build:
      dockerfile: Dockerfile.claude-agent
    volumes:
      - ./bare-repo:/upstream:ro
      - tests-workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_INITIAL_PROMPT=Write integration tests for payment API

  agent-docs:
    build:
      dockerfile: Dockerfile.claude-agent
    volumes:
      - ./bare-repo:/upstream:ro
      - docs-workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - CLAUDE_INITIAL_PROMPT=Update API documentation

volumes:
  auth-workspace:
  tests-workspace:
  docs-workspace:

# 1. Create a bare repo as the shared upstream
git clone --bare . ./bare-repo

# 2. Launch all agents
docker compose up

# 3. Each agent clones from the bare repo into its own /workspace
#    They work in complete isolation.
#    When done, each pushes to the bare repo on its own branch.

# 4. Pull results back
git fetch ./bare-repo
git merge origin/agent-auth
git merge origin/agent-tests
git merge origin/agent-docs

Physical Setup Tips

Running parallel agents is a software problem until about 4 sessions. After that, the bottleneck shifts from compute to your ability to monitor and direct multiple streams of work simultaneously. Hardware choices matter.

Display

An ultra-wide monitor (34"+) or dual-monitor setup lets you see all panes without switching. At 3 sessions, a single 27" monitor works. At 6+, you need more screen real estate. Some developers use a vertical monitor for the task list and a horizontal one for agent output.

Terminal configuration

Use iTerm2 with a high-contrast color profile. When scanning 4-6 panes, you need to distinguish active output from idle sessions at a glance. Bold fonts and distinct prompt colors per session help. Name your tmux windows or iTerm2 tabs after the task, not the agent number.

Input methods

At 6-8 agents, typing instructions into each pane becomes the throughput bottleneck. Some developers use voice-to-text (Whisper, macOS Dictation) for rapid agent instructions. A foot pedal mapped to push-to-talk lets you dictate without taking hands off the keyboard.

The attention ceiling

Which Method Should You Use

The right method depends on three things: how isolated the tasks need to be, whether agents need to talk to each other, and how much setup you are willing to do.

Frequently Asked Questions

How many Claude Code sessions can I run in parallel?

No hard limit on sessions. Each consumes tokens from your plan. On Claude Max ($100/mo), 3-5 parallel sessions is comfortable. On Max 20x ($200/mo), 6-8 is practical. The practical ceiling is human attention, not compute. Anthropic's team ran 16 agents for their C compiler project, but that was an automated pipeline with minimal human oversight.

What is the -w flag in Claude Code?

The -w (or --worktree) flag creates a new git worktree and starts Claude Code inside it. Running claude -w feature-auth creates a branch called "feature-auth", checks it out in a separate directory, and launches Claude there. Multiple worktrees share git history but have independent file systems. No file conflicts between sessions.

What is the difference between subagents and agent teams?

Subagents are spawned inside one session. They report to the parent but cannot message each other. Agent teams are multiple independent sessions with a shared task list and direct inter-agent messaging. Use subagents for 3-5 independent subtasks. Use agent teams when agents need to coordinate or when tasks have dependencies.

Do parallel sessions cost more?

Yes. Each session consumes tokens independently. Five parallel sessions use roughly 5x the tokens of one session. On subscription plans, this drains your limit faster. On API billing, you pay per token. The cost pays off when parallel work finishes in 20 minutes what sequential work takes 2 hours.

Can I mix methods?

Yes. A common pattern: use git worktrees for the top-level split (one worktree per feature), then use subagents within each worktree session for finer-grained parallelism. Or use agent teams for the coordinated part of the work and separate worktree sessions for independent tasks.

What about VS Code?

The Claude Code VS Code extension runs as a single session per window. Open multiple VS Code windows, each pointed at a different worktree, to get parallel sessions in the IDE. The CLI is more natural for parallel work because terminal panes are lighter weight than full editor windows.