Running a Fleet of
Claude Coding Agents

One developer, many agents, zero chaos. Ten battle-tested tips for parallelizing your coding with Claude Code — gathered from the latest guides, docs, and production war stories.

Why run a fleet instead of one agent?

Split spec-first, not hope-first

One spec per unit of work, each with clear success criteria. The spec is your parallel boundary — it decides what can run side by side.

What a fleet-ready spec looks like

One self-contained brief per agent. Notice: context, boundaries, and a pass/fail check the agent can't argue with.

TRACK A — rate limiting  ·  worktree ../app-agentA  ·  branch agentA/rate-limit

GOAL      Add per-IP rate limiting to the login endpoint in
            src/routes/login.ts (currently no throttling).
RULES     100 requests / 15 min per IP; 429 + Retry-After on excess;
            follow the middleware pattern in src/middleware/auth.ts.
OUT OF SCOPE  Don't touch the signup flow or the DB schema.
DONE WHEN npm test -- login passes, plus a new test file
            tests/login-rate-limit.test.ts covering the 429 path.
REPORT BACK  JSON: files changed, tests added, pass/fail.

One worktree per agent

Agents that edit files must never share a working tree — that's how write conflicts and mystery breakages happen.

# each agent: isolated checkout + branch + port + database
git worktree add ../app-agent1 -b agent1
git worktree add ../app-agent2 -b agent2
# agent1 → PORT=3000, db app_agent1 · agent2 → PORT=3001, db app_agent2

Write prompts like the agent has amnesia

Because it does. Every subagent wakes up with zero context from your conversation — no shared memory, no memory of earlier runs.

Cast specialists, not clones

Define agents with /agents — they're just markdown files in .claude/agents/. Give each one a job, and restrict its tools.

---
name: reviewer
description: Checks finished work against its task spec. Use after any agent reports done.
tools: Read, Grep, Glob
---
You are a review agent. You never edit files — you only report pass or fail,
quoting the exact lines that miss the spec.

Writer ≠ Reviewer

The single highest-value fleet pattern: one agent writes, a different, fresh agent reviews. Claude won't be biased toward code it just wrote — the reviewer reads it cold.

Cap the fleet: 3–5 is the sweet spot

More agents isn't more speed. Subagents can't talk to each other mid-run, so you pay the synthesis cost for every report they send back.

• 3–5 parallel agents — the practical ceiling for most workflows
• ~10 max for genuinely independent tracks (research, audits)
• Beyond that, coordination overhead and rate-limit pressure eat the gains
• The quiet winner: one background agent (full test suite, codebase search) while your main session does focused editing

Don't over-delegate

Spawning an agent has real overhead: context setup, prompt processing, result synthesis. For a three-line fix, just do it yourself.

JSON in, report out

Tell every agent exactly how to report back. Structured output lets the orchestrator aggregate results instead of reading essays.

Have each subagent return JSON:
{ "file": "src/auth/middleware.ts",
  "issues": [{ "line": 42, "severity": "high", "description": "…" }] }

Guardrails before autopilot

Subagents inherit your full model tier with no built-in spending cap. Wire in the guardrails before you walk away.

• Stop hooks — deterministic checks that run when an agent finishes, for auditable workflows
• Cost caps — track tokens per agent, set max iterations, watch the meter live
• /permissions wildcards — Bash(npm run *), Edit(/docs/**) instead of --dangerously-skip-permissions
• /sandbox — file + network isolation, fewer permission prompts, safer fleet

Go long: the Ralph Wiggum loop

For missions that take hours, not minutes — ship code while you sleep. A bash loop re-feeds the task until it's actually done.

# iteration beats perfection — each run reads git history + progress log,
# picks the next task, implements, tests, commits, logs, repeats
while :; do cat PROMPT.md | claude ; done

• Objective done-criteria — tests pass and the build succeeds, never the agent's self-assessment
• JSON task board + progress log — structured state survives between iterations
• Start --max-iterations small (10–20), scale up once you know the token burn

Prompts you can steal

Three prompts that put the tips to work. Adapt the paths — keep the structure.

"Run 3 subagents in parallel.
Agent 1: implement TRACK A
in ../app-agentA.
Agent 2: implement TRACK B
in ../app-agentB.
Agent 3: review both against
their specs (read-only tools).
Each returns JSON. Give me a
merged go/no-go."

"You have fresh eyes and zero
memory of this code. Read spec
TRACK A and the diff in
../app-agentA. Report pass/fail
per criterion, quoting the exact
lines that miss. Do not edit
any files."

"Read progress.txt and git log.
Pick the first task in
features.json with passes=false.
Implement it, run tests + lint.
Commit only if green, set
passes=true, log progress,
then exit."

Your first fleet, in six steps

Also worth knowing: /loop for recurring jobs (babysit PRs, poll deploys), cross-session messaging so agents pass findings along, and agent teams — experimental auto-coordination with a team lead.

Sources

🐾 Built by Meow · September 2026