Claude Code multi-agent: run parallel agents on different parts of your codebase

One of the most underused features in Claude Code is the ability to spawn multiple agents working simultaneously on different parts of your project. Instead of waiting for one agent to finish, you can have three agents running in parallel — one fixing bugs, one writing tests, one updating docs.

Here's exactly how to set it up.

The basic pattern

# Terminal 1 — Agent working on the API layer
cd /your/project
claude "Refactor all the route handlers in src/routes/ to use async/await consistently. Fix any error handling gaps you find."

# Terminal 2 — Agent working on tests (same project)
claude "Write unit tests for every function in src/utils/. Use Jest. Aim for 90% coverage."

# Terminal 3 — Agent updating documentation
claude "Update README.md and all JSDoc comments to match the current API signatures in src/routes/."

These run simultaneously. Each agent has its own context window, its own conversation, its own tool calls.

Why this works without conflicts

Claude Code agents don't share state. Each one reads files fresh when it needs them. As long as they're working on different files or different logical areas, they won't step on each other.

The key is giving each agent a bounded scope:

# Good — bounded scopes
claude "Work only on files in src/api/"
claude "Work only on files in src/tests/"
claude "Work only on files in docs/"

# Risky — overlapping scopes
claude "Improve the codebase"
claude "Fix all the bugs"

The CLAUDE.md coordination trick

If you're running agents on the same repo, use CLAUDE.md to coordinate:

# CLAUDE.md

## Active agent assignments
- Agent A owns: src/api/, src/routes/
- Agent B owns: src/tests/, src/fixtures/
- Agent C owns: docs/, README.md

## Shared files (read-only for agents)
- src/types/index.ts — do not modify, coordinate with human
- package.json — do not modify, coordinate with human
- .env — do not read or modify

Every agent reads this. They know their lane.

Rate limits kill parallel agents fast

Here's the problem with running 3 agents simultaneously: you hit Anthropic's rate limits in minutes.

Each agent is hammering the API independently. If you're on the free tier or a standard API key, you'll see:

API Error: overloaded_error
Rate limit exceeded. Please retry after 60 seconds.

...on all three terminals simultaneously.

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

export ANTHROPIC_BASE_URL=https://simplylouie.com

Then run all three agents. They all go through the proxy. The $2/month subscription at simplylouie.com removes the rate cap — designed exactly for this multi-agent pattern.

# Set once, applies to all terminals in the session
export ANTHROPIC_BASE_URL=https://simplylouie.com

# Now all three agents share the rate limit headroom
terminal 1: claude "Refactor src/api/"
terminal 2: claude "Write tests for src/utils/"
terminal 3: claude "Update docs/"

Orchestrator + subagent pattern

For more complex work, use one agent as the orchestrator:

# The orchestrator agent
claude "You are the orchestrator. Use the Task tool to spawn three subagents:
1. Subagent A: Audit all API endpoints in src/routes/ and list any missing input validation
2. Subagent B: Check all database queries in src/db/ for SQL injection risks
3. Subagent C: Review all auth middleware in src/middleware/ for JWT handling issues

Wait for all three to complete, then compile their findings into a security_audit.md file."

Claude Code's Task tool lets a single agent spawn parallel workers. The orchestrator coordinates, subagents do the work.

Git workflow for parallel agents

When agents are writing to the same repo, use branches:

# Before starting parallel agents
git checkout -b agent-api-refactor
# Terminal 1 runs here

git checkout -b agent-test-coverage
# Terminal 2 runs here

git checkout -b agent-docs-update
# Terminal 3 runs here

# After all three finish
git checkout main
git merge agent-api-refactor
git merge agent-test-coverage
git merge agent-docs-update

Each agent works on its own branch. You merge when they're done. No conflicts.

Practical example: shipping a feature in parallel

Here's a real workflow for shipping a new feature:

# Set rate limit proxy first
export ANTHROPIC_BASE_URL=https://simplylouie.com

# Agent 1: Implement the feature
claude "Implement a user notifications system. Create src/notifications/index.js with 
functions: createNotification(userId, type, data), getNotifications(userId), markRead(notificationId). 
Store in SQLite. Follow the patterns in src/users/index.js."

# Agent 2: Write tests immediately (same time)
claude "Write Jest tests for a user notifications module that will have these functions: 
createNotification(userId, type, data), getNotifications(userId), markRead(notificationId). 
Create src/notifications/index.test.js. Mock the database. Test happy path and error cases."

# Agent 3: Document it immediately (same time)
claude "Write API documentation for a user notifications endpoint. Assume POST /notifications 
creates one, GET /notifications/:userId gets them, PATCH /notifications/:id/read marks read. 
Create docs/notifications-api.md with curl examples."

Feature, tests, and docs — all in parallel. What used to take three sequential sessions now takes one.

Monitoring what your agents are doing

# Watch all agent activity in real time
tail -f ~/.claude/logs/*.log

# See all active Claude Code processes
ps aux | grep claude

# Kill a runaway agent
pkill -f "claude.*agent-api"

The checklist for parallel agents

• [ ] Define bounded scopes in CLAUDE.md
• [ ] Use separate git branches per agent
• [ ] Set ANTHROPIC_BASE_URL to avoid rate limits
• [ ] Give each agent explicit file/folder ownership
• [ ] List shared read-only files they shouldn't modify
• [ ] Monitor with tail -f ~/.claude/logs/*.log
• [ ] Merge branches after all agents complete

Parallel agents are one of the highest-leverage things you can do with Claude Code. The setup takes 10 minutes. The time savings compound across every feature you ship after.

---

Running multiple agents? The rate limits stack fast. simplylouie.com removes them for $2/month — built for exactly this pattern.