Parallel Claude Code Agents: How to Speed Up Coding Without Breaking Your Repo

Running more Claude Code agents does not automatically make development faster. It often makes the merge, testing, and review problem worse unless the work is isolated, scoped, and validated. Parallel Claude Code agents work best when you treat them like junior-to-mid-level implementation workers inside a disciplined engineering process. The core pattern is simple: plan first, define shared contracts, split work by ownership boundaries, isolate each worker in a git worktree, run tests per worker, then validate the merged result in one final pass.

Claude Code now has several ways to parallelize work: worktrees, subagents, agent view, agent teams, and /batch. The right choice depends on whether you need file isolation, delegated context, autonomous coordination, or repo-wide mechanical changes. Claude’s official docs describe worktrees as isolated checkouts for parallel file edits, subagents as delegated workers inside one session, and agent teams as coordinated sessions with shared task lists and messaging. ([Claude][1])

Parallel Claude Code agents are safest when each worker owns a clearly bounded part of the codebase, works in its own git worktree, runs local tests, and returns a diff that is reviewed and merged in dependency order.

Table of Contents

• Can you run multiple Claude Code agents in parallel?
• Why parallel AI coding fails
• The main ways to parallelize Claude Code work
• Worktrees vs subagents vs agent teams
• The operating model
• How to split work between agents
• How agents coordinate git, testing, and integration
• How to write CLAUDE.md without bloating context
• How to use AGENTS.md
• Practical templates
• Common failure modes
• Decision checklist
• FAQ
• Key takeaways

Can you run multiple Claude Code agents in parallel?

Yes. You can run parallel Claude Code work in several ways:

• Start multiple Claude Code sessions in separate git worktrees.
• Use subagents inside one Claude Code session.
• Use subagents with isolation: worktree.
• Use agent teams for coordinated multi-agent work.
• Use /batch for large repo-wide mechanical changes.

Claude Code builds on that idea. With claude --worktree feature-auth, Claude creates an isolated checkout under .claude/worktrees// and starts a session there. The official Claude Code docs also recommend adding .claude/worktrees/ to .gitignore so these directories do not show up as untracked files in your main checkout. ([Claude][1])

Example:

<h1>Terminal 1</h1>
claude --worktree feature-auth
<h1>Terminal 2</h1>
claude --worktree fix-session-expiry
<h1>Terminal 3</h1>
claude --worktree refactor-user-service

This prevents agents from overwriting each other’s files on disk. It does not remove the need for integration discipline.

Why parallel AI coding fails when teams treat it like “more typing speed”

The obvious benefit of parallel Claude Code agents is speed. One agent can implement the backend, another can write frontend changes, another can generate tests, and another can review the diff.

The trap is assuming that coding speed is the bottleneck.

For senior engineers, the bottleneck is usually not typing. It is coordination: shared types, assumptions, tests, migrations, branch state, review quality, and final integration.

Parallel AI coding fails in five common ways:

Do not think “I have five coders now.” Think “I am managing five isolated implementation branches that must converge into one correct system.”

That is an engineering management problem, not just a Claude Code feature.

What are the main ways to parallelize Claude Code work?

Claude Code gives you multiple parallelization primitives. They are not interchangeable.

Git worktrees for isolated file edits

Use worktrees when multiple sessions or agents may edit files.

Worktrees isolate working directories, branches, and file changes. Claude Code’s worktree mode creates a new branch named worktree- by default and creates the worktree under .claude/worktrees//. ([Claude][1])

Example:

claude --worktree backend-auth
claude --worktree frontend-auth
claude --worktree auth-tests

Use this when:

• You want multiple terminal sessions.
• You want each session to commit to its own branch.
• You want to avoid agents clobbering one another’s local edits.
• You can review and merge branches deliberately.

Subagents for delegated focused work

Subagents are specialized AI assistants inside Claude Code. Anthropic describes them as workers with their own context window, custom system prompt, tool access, permissions, and model configuration. They are useful when a side task would flood the main conversation with logs, search results, or file contents. ([Claude][3])

Subagents are good for:

• Codebase exploration.
• Test writing.
• Code review.
• Debugging a contained error.
• Searching logs or tracing references.
• Implementing a bounded module.

---
name: code-reviewer
description: Reviews code for correctness, maintainability, and security
tools: Read, Glob, Grep, Bash
model: sonnet
You are a senior code reviewer.
Review the changed files only. Focus on:
correctness
edge cases
security issues
test coverage
consistency with project conventions
Do not modify files. Return actionable findings with file paths and line references.

Claude Code supports frontmatter fields such as name, description, tools, model, permissionMode, skills, background, and isolation. name and description are required. ([Claude][3])

Subagents with worktree isolation

For implementation agents, use worktree isolation.

Claude Code supports setting isolation: worktree in subagent frontmatter. Anthropic’s docs say subagents can run in their own worktrees so parallel edits do not conflict, and you can either ask Claude to “use worktrees for your agents” or configure it permanently in the custom subagent. ([Claude][1])

Example:

---
name: backend-builder
description: Implements backend changes in isolated worktrees
tools: Read, Glob, Grep, Bash, Edit, Write
model: sonnet
isolation: worktree
You are a backend implementation agent.
Rules:
Work only in backend-owned directories assigned by the orchestrator.
Do not edit shared schema, migrations, lockfiles, or root config unless explicitly assigned.
Run targeted tests before reporting done.
Commit your changes to your worktree branch.
Report changed files, test results, and unresolved risks.

This is the default pattern for parallel implementation.

Agent teams for coordinated multi-agent work

Agent teams are different from subagents. They are coordinated sessions with a lead, teammates, a shared task list, and direct messaging between teammates.

Anthropic marks agent teams as experimental and disabled by default. They can be enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the environment or settings. ([Claude][4])

Agent teams are useful when workers need to discuss, challenge, or coordinate with one another. The docs describe teammates as independent Claude Code sessions that coordinate through a shared task list and can message each other directly. ([Claude][4])

Use agent teams when:

• The problem is complex enough to justify coordination overhead.
• You want one teammate to challenge another’s approach.
• The task involves research, architecture, and implementation.
• You can tolerate higher token usage.

• Tasks are sequential.
• Multiple workers need to edit the same files.
• You just need a simple bug fix.
• You do not have time to supervise the output.

/batch for large mechanical changes

Claude Code’s /batch command is designed for large changes across a codebase. Official docs describe /batch as a skill that researches the codebase, decomposes work into 5 to 30 independent units, presents a plan, then spawns one background subagent per unit in an isolated git worktree. Each subagent implements its unit, runs tests, and opens a pull request. ([Claude][5])

Use /batch for:

• Mechanical migrations.
• API renames.
• Framework migrations.
• Repo-wide type cleanup.
• Repetitive changes with clear rules.

Worktrees vs subagents vs agent teams: which should you use?

Use worktrees for isolation, subagents for delegation, agent teams for coordination, and /batch for large mechanical changes.

Do not start with the most complex mechanism. Start with two worktrees or two subagents. Increase concurrency only when your review process can keep up.

The operating model: plan, scaffold, split, validate, merge

The safest parallel Claude Code workflow is:

• Plan
• Scaffold
• Split
• Dispatch
• Test locally
• Merge deliberately
• Validate integrated output
• Clean up

1. Plan before agents write code

Ask Claude to inspect the repo and propose a work split before creating agents.

Prompt:

We need to implement [feature].
First, do not edit files. Analyze the codebase and produce:
affected modules
shared contracts that must be defined before implementation
independent work packages
files/directories each agent should own
tests required per package
merge order
risks
Only after I approve the plan should you spawn agents.

Claude Code supports planning workflows, and its docs recommend planning before editing for changes you want to review before files are touched. ([Claude API Docs][6])

2. Scaffold shared contracts sequentially

Do not let multiple agents invent shared contracts independently.

Before parallel implementation, define:

• API request/response shape.
• TypeScript interfaces.
• OpenAPI schema.
• Database migration design.
• Event names.
• Error format.
• Directory ownership.
• Test strategy.

Example:

Before spawning implementation agents, create only the shared contract files:
src/contracts/auth.ts
docs/auth-flow.md
tests/fixtures/auth-fixtures.ts
Do not implement feature logic yet.

3. Split by ownership boundary, not by vague feature label

Bad split:

• Agent 1: “do auth”
• Agent 2: “do login”
• Agent 3: “do frontend”

Agent 1 owns src/api/auth/* Agent 2 owns src/session/* Agent 3 owns src/components/login/* Agent 4 owns tests/auth/*

The output should be separable, reviewable, and mergeable.

4. Dispatch agents with worktree isolation

Prompt:

Use worktrees for implementation agents.
Spawn three agents in parallel:
backend-builder: implement src/api/auth/<em></em> using the existing contract.
session-builder: implement src/session/<em></em> only.
test-author: write tests under tests/auth/<strong> and tests/session/</strong>.
Each agent must:
stay inside its ownership boundary
run targeted tests
commit changes on its worktree branch
report changed files, commands run, test result, and risks
Do not allow any agent to edit:
package-lock.json
pnpm-lock.yaml
migrations
root config
shared contract files
unless explicitly assigned.

5. Test locally inside each worktree

Each agent should run the smallest meaningful test set first:

pnpm test tests/auth
pnpm typecheck
pnpm lint src/api/auth

Claude Code’s best practices recommend preferring single tests over whole test suites for performance during development, then typechecking after a series of code changes. ([Claude][7])

6. Merge in dependency order

Do not merge branches randomly.

Merge order should follow dependency order:

• Contracts and shared types.
• Backend logic.
• Frontend integration.
• Tests.
• Docs.
• Refactors.

7. Validate the integrated tree

After merging, run a final validation pass from the main branch.

Prompt:

Now act as an integration validator.
Read the merged diff and verify:
contracts are used consistently
no agent duplicated logic
error handling matches project conventions
tests cover success, failure, and edge cases
no unowned files were modified
typecheck, lint, and targeted tests pass
Do not make changes yet. Report findings first.

Then run:

pnpm typecheck
pnpm lint
pnpm test

If the full suite is expensive, run critical suites first, but do not ship without a final integrated check.

8. Clean up worktrees

Worktrees accumulate. Claude Code can remove clean worktrees automatically in some cases, but non-interactive runs are not automatically cleaned up and may need git worktree remove. ([Claude][1])

Useful commands:

git worktree list
git worktree prune
git branch --merged

How should you split work between Claude Code agents?

Use this rule:

An agent should own a directory, layer, or test surface — not an abstract idea.

Good agent boundaries:

Propose a parallelization plan.
Rules:
Max 3 implementation agents.
Each agent must own non-overlapping directories.
Shared contracts must be created before implementation.
No agent may edit lockfiles, migrations, root config, or shared interfaces unless assigned.
Each agent must have a clear done condition and test command.
Include a merge order and final validation plan.

---

How should agents coordinate git, testing, and integration?

Agents do not magically solve coordination. You need explicit coordination surfaces.

1. Branch and worktree naming

Use predictable names:

worktree/auth-contracts
worktree/auth-api
worktree/auth-ui
worktree/auth-tests

Or:

agent/auth-api
agent/auth-session
agent/auth-validator

2. Shared task file

Create a file such as:

.claude/tasks/auth-parallel-plan.md

Example:

<h1>Auth Feature Parallel Plan</h1>
<h2>Shared contracts</h2>
Owner: main session  
Files:
src/contracts/auth.ts
docs/auth-flow.md
Status: complete
<h2>Agent: backend-builder</h2>
Owns:
src/api/auth/<em></em>
src/services/auth/<em></em>
Must not edit:
src/contracts/auth.ts
migrations/<em></em>
package files
Test command:
pnpm test tests/api/auth
Status: in progress
<h2>Agent: frontend-builder</h2>
Owns:
src/components/login/<em></em>
src/pages/login/<em></em>
Test command:
pnpm test tests/ui/login
Status: pending

Agent teams have an internal shared task list and teammate messaging. But for standard subagents and worktrees, a simple checked-in or local markdown task file keeps coordination visible. Claude’s agent team docs also describe task states, dependencies, self-claiming, and file locking for team task coordination. ([Claude][4])

3. Test ownership

Every agent should know its test command before it starts.

Example:

<h2>Done condition</h2>
You are done only when:
implementation is complete
targeted tests pass
typecheck passes for affected package
changed files are listed
risks are reported

4. Hooks for non-negotiable gates

Instructions in CLAUDE.md are advisory. Hooks are stronger.

Claude Code hooks can run at lifecycle events such as before tool use, after tool use, when a subagent starts/stops, when a task is created/completed, or when a worktree is created/removed. The hooks reference lists events such as SubagentStart, SubagentStop, TaskCreated, TaskCompleted, WorktreeCreate, and WorktreeRemove. ([Claude API Docs][8])

Use hooks for rules like:

• block writes to migrations unless explicitly allowed
• run formatter after edits
• block rm -rf
• prevent task completion unless tests were run
• inject security checklist into reviewer agents

When a subagent stops, check whether its final message includes:
changed files
test command
test result
risks
If missing, return feedback and keep the subagent working.

How to write CLAUDE.md without bloating context

CLAUDE.md should be a map, not a manual.

Claude Code’s best practices say CLAUDE.md is read at the start of every conversation and should include commands, code style, workflow rules, and persistent context that Claude cannot infer from code alone. The same docs explicitly warn that bloated CLAUDE.md files cause Claude to ignore instructions and recommend keeping it concise. ([Claude][7])

Use this rule:

Put only always-needed rules in root CLAUDE.md. Move task-specific or directory-specific knowledge elsewhere.

What belongs in root CLAUDE.md

• Setup commands.
• Test commands.
• Package manager.
• Branch conventions.
• Critical architecture invariants.
• Parallel-agent operating rules.
• Files agents must not edit without approval.
• Where project docs live.

What does not belong in root CLAUDE.md

• Full API documentation.
• Long architecture tutorials.
• File-by-file explanations.
• Rare deployment procedures.
• Everything you are annoyed Claude forgot once.

Recommended structure

repo/
├── CLAUDE.md
├── AGENTS.md
├── README.md
├── docs/
│   ├── architecture-brief.md
│   ├── glossary.md
│   ├── conventions.md
│   └── testing.md
├── src/
│   ├── api/
│   │   └── CLAUDE.md
│   ├── components/
│   │   └── CLAUDE.md
│   └── workers/
│       └── CLAUDE.md
└── .claude/
    ├── agents/
    ├── skills/
    └── hooks/

Root CLAUDE.md should point Claude to the right information, not contain all of it.

How to use AGENTS.md for reusable agent instructions

AGENTS.md is an open format for giving coding agents repo-specific instructions. Its own documentation describes it as a “README for agents” and recommends using it for setup commands, tests, and conventions that help agents work on a project. ([Agents][9])

Use AGENTS.md for cross-tool guidance:

• setup commands
• test commands
• code style
• PR expectations
• repository layout
• review rules
• agent role definitions

• Claude memory
• @ imports
• Claude-specific workflow rules
• subagent usage instructions
• worktree and hook policies

Practical templates: CLAUDE.md, AGENTS.md, .worktreeinclude, and agent files

Root CLAUDE.md template

md
<h1>CLAUDE.md</h1>
<h2>Project knowledge map</h2>
Read these before making non-trivial changes:
Project overview: @README.md
Architecture brief: @docs/architecture-brief.md
Glossary/domain terms: @docs/glossary.md
Coding conventions: @docs/conventions.md
Testing guide: @docs/testing.md
Do not load long docs unless needed. Prefer targeted reads.
<h2>Core workflow rules</h2>
Plan before editing for non-trivial tasks.
For parallel work, use scaffold-then-split:
   
- define shared contracts first
   - then dispatch implementation agents
Do not spawn parallel agents for trivial changes.
Prefer 2–3 implementation agents by default.
Split work by directory ownership, not vague feature labels.
Each agent must run targeted tests before reporting done.
After merging parallel work, run integrated validation.
<h2>Parallel-agent rules</h2>
Use worktrees for implementation agents.
Agents must not edit these unless explicitly assigned:
package-lock.json
pnpm-lock.yaml
yarn.lock
migrations/<em></em>
root config files
shared contract files
deployment scripts
Each agent must report:
assigned scope
files changed
commands run
test results
unresolved risks
branch/worktree name
<h2>Testing commands</h2>
Use the smallest meaningful test first:

Before final merge, run:

<h2>Cost-control rules</h2>
Do not spawn agents for work under ~5 minutes.
Do not let multiple agents independently explore the same files.
Use read-only exploration agents before implementation if the repo area is unfamiliar.
Do not spawn agents from agents.
Stop after two failed repair attempts and ask for a better plan.
<h2>Review rule</h2>
Never declare parallel work complete until the integrated branch has been validated.

<h1>AGENTS.md</h1>
<h2>Purpose</h2>
This file gives AI coding agents the operational rules for this repository.
<h2>Setup commands</h2>

<h2>Test commands</h2>

For targeted tests:

<h2>Repository layout</h2>

<h2>Code style</h2>
Follow existing patterns before introducing new ones.
Keep public contracts stable unless assigned to change them.
Prefer explicit types for exported functions.
Do not silently change error formats.
Do not add dependencies without approval.
<h2>Parallel work rules</h2>
Agents must own non-overlapping paths.
Before parallel implementation:
shared contracts must exist
ownership boundaries must be listed
test commands must be assigned
merge order must be known
Agents must not edit:
lockfiles
migrations
root config
shared contracts
  
unless explicitly assigned.
<h2>Completion report</h2>
Every agent must report:

<h2>Review requirements</h2>
Before merge:
review diff
run targeted tests
check type errors
check unowned file edits
validate integrated branch

.env.local
.env.development
config/local-secrets.json

---
name: backend-builder
description: Implements backend changes in assigned directories using worktree isolation
tools: Read, Glob, Grep, Bash, Edit, Write
model: sonnet
isolation: worktree
You are a backend implementation agent.
You must:
work only inside assigned backend directories
follow docs/conventions.md
use existing error-handling patterns
run targeted backend tests
commit your changes
report changed files and risks
You must not:
edit lockfiles
edit migrations
edit shared contracts
change public API shape
unless the parent session explicitly assigns that scope.

---
name: diff-reviewer
description: Reviews changed files for correctness, edge cases, security, and project consistency
tools: Read, Glob, Grep, Bash
model: sonnet
You are a read-only senior code reviewer.
Review only the changed files and related contracts.
Focus on:
correctness
edge cases
test coverage
security risk
consistency with existing patterns
hidden integration failures
Do not edit files.
Return:
must-fix issues
should-fix issues
tests missing
questions for the implementer
final merge recommendation

---
name: codebase-explorer
description: Read-only agent for exploring unfamiliar code areas before implementation
tools: Read, Glob, Grep, Bash
model: haiku
You are a read-only exploration agent.
Your job:
find relevant files
identify existing patterns
summarize architecture
list risky files
recommend ownership boundaries
Do not modify files.
Do not propose large refactors unless asked.
Return concise findings with file paths.

We need to implement: [feature description]
Use the parallel-agent operating model.
Phase 1: Plan only.
Analyze affected modules.
Identify shared contracts.
Propose agent split.
Assign directory ownership.
Define test commands.
Define merge order.
Identify risks.
Do not edit files yet.
Phase 2: After approval, scaffold shared contracts.
Create or update only shared interfaces/docs/fixtures.
Commit scaffold separately.
Phase 3: Dispatch implementation agents.
Use worktrees.
Max 3 implementation agents.
Each agent owns non-overlapping directories.
Each agent runs targeted tests.
Each agent reports changed files, test result, and risks.
Phase 4: Merge and validate.
Merge in dependency order.
Run integrated typecheck, lint, and tests.
Use a read-only reviewer before final completion.

src/contracts/<em></em>
migrations/<em></em>
package.json
pnpm-lock.yaml
.env*
deployment/<em></em>
infra/<em></em>

{
  "user_id": 123,
  "session_token": "abc"
}

{
  "userId": 123,
  "token": "abc"
}

main repo: 3000
worktree-auth-api: 3001
worktree-auth-ui: 3002
worktree-tests: 3003