Claude Code Subagent Limits: How Many Can Run in Parallel

Claude Code doesn't publish one official hard cap on simultaneous subagents in its docs — the number people repeat varies by source and by what counts as 'running' (queued vs. actively executing), so treat any specific figure you see online as unverified unless it links to Anthropic's own docs. What is documented and stable: each subagent's frontmatter can pin its own model, and each subagent run gets an isolated context window that returns only a final report to the main thread. Last updated 2026-11-16 by Rakshit Yadav.

How many subagents can run at once — and the unverified '10' claim

If you've searched this, you've likely seen a number like "10 subagents can run in parallel" repeated across forum threads and blog posts without a citation. We looked for an authoritative source for that specific figure in Anthropic's own Claude Code documentation and didn't find one published there — which means it's either an observed default from a specific version, a conflation with a different limit (like max turns or max tool calls per turn), or just a number that spread because it sounded precise. We're not going to repeat it here as fact.

What's actually true in practice, and verifiable by just watching a session: Claude Code can dispatch multiple subagents for independent parts of a task, and they execute concurrently rather than strictly one-at-a-time, but the main agent still has to synthesize their reports when they return — so throwing more subagents at a task past the point where their outputs depend on each other stops helping and starts adding coordination overhead. If a specific session-level concurrency cap matters for your use case, check your installed Claude Code version's own changelog and settings rather than trusting a number from a forum post with no version attached.

Setting a different model per subagent in frontmatter

This part is documented and stable, not disputed: a subagent's definition file (.claude/agents/<name>.md) carries YAML frontmatter with a model field alongside name, description, and tools. Setting it pins that specific subagent to a model regardless of which model is running the main conversation.

---
name: code-reviewer
description: Reviews diffs for correctness bugs. Never implements fixes.
tools: Read, Grep, Glob
model: claude-sonnet-5-5
---

The practical reason to set this per-agent rather than leaving every subagent on whatever model the main session uses: a review or classification pass that just has to apply a fixed rulebook doesn't need the most expensive model available, while a subagent doing open-ended architecture work benefits from the strongest one. Omitting model lets the subagent inherit the main session's model, which is the simplest default and the right choice until you've actually measured a specific role costing more than its output is worth.

Context isolation: why subagents don't pollute the main thread

A subagent call runs in its own context window — its tool calls, intermediate reasoning, and any files it reads never land in the main conversation's history. Only its final report does. That's the entire reason to reach for a subagent over just asking the main agent to do the work inline: a security audit or a long research pass can take dozens of tool calls, and if those ran in the main thread directly, every one of them would stay in context for the rest of the session, getting re-read by the model on every subsequent turn.

This is also why subagent sprawl has a real cost even though it doesn't bloat context the way CLAUDE.md does: each subagent invocation re-reads whatever files it needs from scratch, because it doesn't inherit the main thread's already-loaded context. Two subagents that could plausibly both claim the same task will sometimes both end up reading the same file in the same session — a failure mode detailed in our own audit of a 34-subagent setup, where fixing it meant narrowing agent descriptions, not adding more isolation.

Subagent vs. skill vs. hook: the concurrency angle

The concurrency question only applies to subagents, which is itself a reason to check whether a job needs to be one. A skill runs inline in the current context — there's no separate instance to count, so "how many skills run in parallel" isn't a meaningful question. A hook fires on a lifecycle event outside the model loop entirely, deterministically, with no concurrency limit to reason about because it's a script, not a model call. See CLAUDE.md vs Skills vs Subagents vs Hooks for the full decision table. The short version for this question: if you're hitting a subagent concurrency ceiling, the first thing to check isn't "how do I raise the limit" — it's whether some of those parallel subagent calls should have been a single subagent doing sequential work, or a skill that didn't need isolation at all.

How AgenticKit's 34-agent team maps to concurrency

AgenticKit's 34 subagents are split into an engineering kit and a marketing kit specifically so a given /ship or /launch run only ever dispatches the handful of role-scoped agents relevant to that command — not all 34 at once. tech-lead coordinates a chain where each specialist (code-reviewer, backend-architect, and others) is invoked for its own scoped piece, with models already set per role in the agent frontmatter, rather than leaving a founder to guess which 3-4 of 34 agents a given feature actually needs running at once.

Related pages

Frequently asked questions

  • Is it true that Claude Code can only run 10 subagents in parallel?
    We could not find that specific number in Anthropic's published Claude Code documentation, so treat it as unverified. Concurrency behavior can also depend on your Claude Code version. Check your installed version's own docs or changelog rather than relying on an uncited figure from a forum post.
  • How do I set a different model for one subagent?
    Add a model field to that subagent's YAML frontmatter in .claude/agents/<name>.md, e.g. model: claude-sonnet-5-5. Omitting it makes the subagent inherit whatever model the main session is running.
  • Do subagents share context with the main conversation?
    No. Each subagent call runs in its own isolated context window and only its final report returns to the main thread — its intermediate tool calls and file reads never land in the main conversation's history.
  • If two subagents could both do a task, does running them in parallel help?
    Usually not. If their descriptions overlap enough that either could plausibly claim the same task, you risk both reading the same files independently and the main agent re-synthesizing redundant work, not real parallelism. Narrow each agent's scope instead of relying on concurrency to sort it out — see our own audit for a concrete example.
  • Should I use a subagent just to get something to run in parallel?
    No — reach for a subagent when the task needs its own context isolation or a distinct role boundary (a reviewer that must not implement, for example). If you just want two independent steps to not block each other and neither needs isolation, that's usually still better modeled as sequential work inside one agent or a skill than as separate subagent calls.

Skip the agent-file guesswork

AgenticKit ships 34 subagents with scoped tool lists and models already set per role, wired into commands that know which ones to invoke together.