Claude Code parallel agents: run 4 tasks simultaneously and merge with git

One of the most underused Claude Code patterns is parallel subagents. Instead of waiting for Claude to finish one task before starting the next, you can spawn multiple agents working simultaneously — then merge.

Here's how to actually do it.

The problem with sequential Claude Code

Default Claude Code is sequential. You give it a task, it works, you give it the next task.

This is fine for small changes. But for big refactors — migrating an API, updating a design system, adding tests to 50 files — sequential means waiting hours for something that could take 20 minutes.

The parallel pattern

The idea is simple: split your work into bounded, independent chunks, run them in parallel, merge the results.

# Terminal 1 — auth module
cd /your/project && git checkout -b agent/auth
claude "Refactor auth.js: add JWT refresh tokens, add rate limiting, add tests. Work only in src/auth/"

# Terminal 2 — user module  
cd /your/project && git checkout -b agent/users
claude "Refactor users.js: add pagination, add search, add tests. Work only in src/users/"

# Terminal 3 — billing module
cd /your/project && git checkout -b agent/billing
claude "Refactor billing.js: add webhook handling, add retry logic, add tests. Work only in src/billing/"

# Terminal 4 — API docs
cd /your/project && git checkout -b agent/docs
claude "Write OpenAPI docs for all endpoints in src/routes/. Work only in docs/"

All 4 run simultaneously. When they're done:

git checkout main
git merge agent/auth agent/users agent/billing agent/docs

Making it work: the three rules

Rule 1: Each agent gets a bounded scope.

Don't let agents work in the same files. Give each agent an explicit work only in X constraint. Otherwise they'll conflict.

# Good
claude "Refactor auth module. Work only in src/auth/"

# Bad  
claude "Refactor the auth stuff" 
# (Claude might touch shared utilities, creating merge conflicts)

Rule 2: Each agent works on its own branch.

This is non-negotiable. Branches let you review each agent's work independently before merging. If one agent breaks something, you discard just that branch.

git checkout -b agent/auth
# Run Claude here
# Review: git diff main..agent/auth
# Merge if good: git merge agent/auth

Rule 3: Tasks must be truly independent.

If task B depends on task A's output, don't parallelize them. Only parallelize work that can be merged cleanly.

Good candidates for parallelization:

• Different modules/directories
• Test writing (read-only on source, writes to test/)
• Documentation (read-only on source, writes to docs/)
• CSS/styling (isolated from logic)

Bad candidates:

• Anything that touches shared utilities
• Migration tasks with sequential dependencies
• Schema changes (one agent changing DB schema affects others)

The orchestrator pattern

For complex projects, add a coordinator step:

# Step 1: Orchestrator plans the work
claude "Analyze this codebase and output a parallelization plan. 
For each independent module, output: module name, files involved, task description.
Do NOT write any code yet. Output JSON."

# Step 2: You review the plan, spawn agents
# Step 3: Agents run in parallel
# Step 4: Orchestrator reviews and merges
claude "Review these 4 branches and create a merge plan. Identify conflicts."

Handling merge conflicts

Conflicts happen when agents touch shared files (imports, config, types). Prevention:

# In each agent's CLAUDE.md or prompt:
Do not modify: 
- package.json
- tsconfig.json  
- src/types/global.ts
- src/utils/shared.ts

If you need a new shared utility, add it to: src/utils/[module-name]-utils.ts

If conflicts happen anyway:

# Let Claude fix them
claude "We have merge conflicts after running parallel agents. 
Here's the conflict output: [paste git diff]
Resolve conflicts preserving both changes where possible."

Real example: adding tests to a large codebase

This is the best use case for parallel agents. Tests are naturally parallel — each agent writes tests for its module without touching other modules.

# Split by directory
git checkout -b agent/test-auth && claude "Write comprehensive tests for all files in src/auth/. 
Use Jest. Aim for 90% coverage. Tests go in tests/auth/"

git checkout main && git checkout -b agent/test-users && claude "Write comprehensive tests for all files in src/users/.
Use Jest. Aim for 90% coverage. Tests go in tests/users/"

git checkout main && git checkout -b agent/test-billing && claude "Write comprehensive tests for all files in src/billing/.
Use Jest. Aim for 90% coverage. Tests go in tests/billing/"

Result: 3x the test coverage in the same time.

Rate limits kill parallel agents

Here's the real problem: run 4 Claude Code agents simultaneously and you'll hit rate limits fast.

The fix is to point all agents at a proxy that removes rate limits:

export ANTHROPIC_BASE_URL=https://simplylouie.com

# Now run all 4 agents — no rate limit errors

SimplyLouie is a Claude proxy at $2/month — simplylouie.com. The ANTHROPIC_BASE_URL swap takes 30 seconds and works with all Claude Code commands unchanged.

The workflow in practice

# Setup
export ANTHROPIC_BASE_URL=https://simplylouie.com  # no rate limits

# Spawn 4 agents in 4 terminals
tmux new-session -d -s agent1 'git checkout -b agent/auth && claude "[task1]"'
tmux new-session -d -s agent2 'git checkout -b agent/users && claude "[task2]"'
tmux new-session -d -s agent3 'git checkout -b agent/billing && claude "[task3]"'
tmux new-session -d -s agent4 'git checkout -b agent/docs && claude "[task4]"'

# Monitor
tmux ls  # see all agents
tmux attach -t agent1  # check progress

# Merge when done
git checkout main
git merge agent/auth agent/users agent/billing agent/docs

When parallel agents are worth it

Use parallel agents when:

• Task has 3+ independent modules
• Each module takes 10+ minutes sequentially
• You have rate limit headroom (or a proxy)

Skip parallel agents when:

• Tasks have dependencies on each other
• You're under a token budget
• The task is simple enough to do sequentially in 5 minutes

The setup overhead (branches, merging, conflict resolution) costs about 10 minutes. Only worth it for tasks where parallelization saves more than that.

---

Running multiple parallel Claude Code agents without rate limit issues requires bypassing Anthropic's default limits. Set ANTHROPIC_BASE_URL=https://simplylouie.com — $2/month Claude proxy at simplylouie.com. 7-day free trial.