Agent swarms in Claude Code are dispatched via the Agent tool, which spawns sub-agents — fresh, forked, or specialized — to run in parallel with optional worktree isolation and the Agent Teams coordination layer for native peer communication.

📝Claude Code provides three distinct agent-spawn modes accessible through the Agent tool: standard sub-agents (fresh context, custom system prompt), forked sub-agents (full parent context cloned, prompt cache shared), and specialized sub-agents (named profile with pre-declared tool permissions). Parallel dispatch is the default — multiple agents launched from a single response run concurrently. The Agent Teams pattern, also called swarm mode, adds native coordination primitives between children: shared task lists, peer messaging, and file locking. Worktree isolation routes each agent's filesystem writes to a separate git worktree, enabling parallel implementation branches without merge conflicts.

How It Works

Standard sub-agents — spawned via the Agent tool with an explicit subagent_type (e.g., Explore, Plan, code-reviewer). Fresh context window with a custom system prompt. The child receives only the task description, not the parent's conversation history.
Forked sub-agents — spawned by omitting subagent_type or invoking the /fork slash command. Inherits the parent's full uncompressed context and shares its prompt cache, making it cheaper than spawning fresh when session context matters. Introduced in Claude Code v2.1.
Policy islands — pair context: fork with a named agent: in skill or command frontmatter to spawn a sub-agent restricted to a pre-declared allowed_tools list. The child runs without mid-workflow approval prompts and returns only a summary.
Agent Teams (swarm mode) — native coordination layer where multiple concurrent agents share a task list, exchange peer messages, and acquire locks on shared resources. Allows mid-flight work subdivision rather than only at dispatch time.
Parallel dispatch — multiple Agent tool calls in a single assistant response execute concurrently. Combined with isolation: "worktree", each child gets its own filesystem branch.
Agent SDK — programmatic access for non-interactive (CI/CD) environments. Fork mode is interactive-only in the application but can be enabled in external builds via CLAUDE_CODE_FORK_SUBAGENT=1.

Why It Matters

Most Claude-based multi-agent architectures live or die on this primitive. The choice between fork, standard, and policy-island sub-agents determines whether deep session context survives, how many approval prompts the human sees, and whether parallel work can safely share a filesystem. Getting the dispatch mode wrong compounds: a fresh sub-agent loses the architectural decisions made deep into a session, an unforked sub-agent for noisy work pollutes the parent's window with debug churn, and a swarm without worktree isolation deadlocks on concurrent file writes.

The Agent Teams primitive specifically — shared task lists, peer messaging, file locks — is what separates a loose swarm (independent agents that may produce contradictory outputs) from a coordinated team (agents that can negotiate work boundaries and avoid conflict). Production multi-agent systems at scale require the latter. Demos and tutorials usually show the former.

FAQ

What is the difference between a sub-agent and a forked sub-agent in Claude Code?

A standard sub-agent gets a fresh context window with a custom system prompt and inherits only a compressed summary of the parent's intent. A forked sub-agent inherits the parent's full uncompressed conversation history and shares its prompt cache, making it cheaper and richer when session context is load-bearing.

How do I run multiple Claude Code agents in parallel?

Invoke the Agent tool multiple times in a single assistant response. Claude Code dispatches them concurrently. For filesystem isolation, pass isolation: "worktree" to each call so each child writes to its own git worktree without merge conflicts.

What is Claude Code Agent Teams (swarm mode)?

Agent Teams is the native coordination layer for multiple concurrent agents in Claude Code. It provides shared task lists, peer messaging, and file locking so agents can subdivide work mid-flight, message each other, and avoid concurrent-write conflicts on shared resources.

Can a forked sub-agent spawn its own forks?

No. A forked sub-agent receives an injected directive that disables further forking. Forks are one level deep by design — recursive forking would explode context costs and create coordination nightmares.

Does fork mode work in CI/CD?

Fork mode is interactive-only inside the Claude Code application. For external builds and CI/CD pipelines, set the environment variable CLAUDE_CODE_FORK_SUBAGENT=1. The Agent SDK in standard non-interactive mode otherwise spawns standard sub-agents.

📝Agent Swarm — the general pattern Claude Code's agent dispatch implements
📝Multi-Agent Orchestration at Scale — production architecture for coordinated systems using these primitives
📝AI Agent Swarms vs. Sequential Review: When Each Wins — when this primitive is the right tool versus a focused sequential pass