Claude Code Subagents: The 3 to 5 Agent Sweet Spot

Claude Code subagents run best at 3 to 5 at once. That number is Anthropic's own recommendation in its agent-teams documentation, and it is enough parallel work to cut total wait time by 50 to 80 percent without hitting rate limits, blowing up the context window, or drowning in coordination. Past five agents, you are no longer doing subagent work: you switch to Dynamic Workflows, a different mode built for big jobs.

---

---

Why this matters to you

If you run too few agents, you wait longer than you need to. If you run too many, Claude Code starts queuing requests, loses track of what each agent is doing, and your bill climbs fast. Knowing the 3 to 5 ceiling, and what to reach for above it, saves you both time and money on every build.

A quick definition first. A "subagent" is a helper that Claude Code spins up inside your session to do one focused job, like searching files or writing tests, then hands the result back to the main agent. You are the manager. The subagents are the workers.

Why the ceiling sits at five

The 3 to 5 number is not folklore from forums. It comes straight from Anthropic's agent-teams docs. Three things all converge around five agents:

1. Orchestrator overhead. The main agent has to track every worker. Each new agent adds bookkeeping to its limited memory (the "context window," the amount of text the model can hold at once). More agents means more of that memory spent on management instead of your actual task.
2. Rate limits. On the entry-level Tier 1 plan, you get roughly 50 requests per minute. Five busy agents can hit that ceiling, after which new requests sit in a queue and your speed gain disappears.
3. Stacking cost. Every agent runs its own context window. Five agents reading the same large codebase means you pay for that context five times over.

Below five, you get the speed without the penalties. That is the whole reason the sweet spot exists.

The three primitives people mix up

Most posts blur three different tools into one. They are not the same thing.

In plain terms:

• Subagents are workers inside one session. The result comes back to you.
• Agent Teams are several full sessions that talk to each other through a shared to-do list. Still experimental. Useful to know about, not something to lean on for production yet.
• Dynamic Workflows is a JavaScript script that the Claude Code runtime runs for you. The in-between results live in plain script variables, not in Claude's memory, so the job can pause and resume. It became generally available on May 28, 2026.

How to create a subagent

A subagent is just a small text file. Here is the anatomy:

1. Create a file at .claude/agents/<name>.md for one project, or ~/.claude/agents/<name>.md to use it everywhere.
2. Add the YAML header. Only name and description are required. The description tells the main agent when to call this worker.
3. Add optional fields to control it: tools (what it is allowed to do), model (which Claude model runs it), permissionMode, maxTurns (how many back-and-forth steps it gets), and effort.

The one lever most write-ups skip is model. You can point cheap, fast jobs at Haiku and save Opus for the hard thinking. Routing a grep-and-read worker to Haiku instead of Opus is roughly a 5 to 25x cost cut for that worker, with no real quality loss on simple lookups. If you write a project guide in your CLAUDE.md file describing each agent's job, the main agent picks the right one more reliably.

A simple decision tree

Match the job to the tool with three questions: how many tasks, how independent are they, and do they touch the same files?

• Independent tasks, no shared files (build feature A while feature B gets tested): use subagents. Keep it to 3 to 5.
• Tasks that must coordinate, where agents need to message each other mid-job: agent teams, knowing it is still experimental.
• Hundreds of tasks, or more than 5 running at once, like a full migration: Dynamic Workflows.

What the cost actually looks like

Plan your budget before you fan out agents. Reported figures from enterprise Claude Code usage put baseline spend around $13 per developer per active day. Running 3 agents at once typically pushes that to $30 to $40 per day. Five to ten agents land at $50 to $130 per day. (These are reported usage ranges, not guarantees, and they swing with your codebase size.)

The model field is your main control knob. Send the dumb jobs to Haiku, keep the reasoning on Opus, and the same workload can cost a fraction of the all-Opus version.

What crossing the ceiling looks like

The clearest proof of the difference: developer Jarred Sumner used Dynamic Workflows to port the entire Bun runtime from the Zig language to Rust. Reported results were about 750,000 lines of code generated, 11 days from start to merge, and 99.8 percent of the test suite passing. You cannot do that with five subagents in one session. That is what the JavaScript-orchestrated mode is for.

The rule of thumb

• 3 to 5 subagents cover about 95 percent of tasks: feature builds, parallel file edits, test runs.
• Dynamic Workflows covers the other 5 percent: large migrations, codebase-wide refactors, multi-PR campaigns.
• Agent teams exist but stay experimental. Try them, do not bet production on them yet.

If you want all of this wired up for you (subagents, skills, hooks, and a production SaaS skeleton with auth, Stripe payments, and row-level security on every table) the Build This Now Code Kit is a $29 one-time build system for Claude Code. It ships apps, not snippets.

FAQ

How many subagents can Claude Code run at the same time?

For most workflows, 3 to 5 concurrent subagents is the official sweet spot in Anthropic's docs. Dynamic Workflows supports up to 16 concurrent agents and 1,000 per run, but it requires Claude Code v2.1.154 or later.

How do you create a subagent in Claude Code?

Create a YAML file at .claude/agents/<name>.md (one project) or ~/.claude/agents/<name>.md (everywhere). Only name and description are required. Optional fields include tools, model (haiku, sonnet, opus, fable, or a full model ID), permissionMode, maxTurns, and effort.

What is the difference between Claude Code subagents and agent teams?

Subagents are workers inside one session that return results to the caller. Agent teams are multiple coordinated sessions with a shared task list and direct messaging between agents. Agent teams are still experimental and require setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

How much does running Claude Code subagents cost?

Reported baseline Claude Code spend averages about $13 per developer per active day. Running 3 concurrent agents typically adds up to $30 to $40 per day, and 5 to 10 agents reach $50 to $130 per day. Routing subagents to Haiku instead of Opus for simple tasks is roughly a 5 to 25x cost reduction per subagent.