Claude Code Teams and Swarms: A Conceptual Architecture

“Multi-agent” is usually presented as a throughput trick: run N agents, get N answers.

Claude Code’s teams/swarms are closer to an operations model: a way to run parallel work without turning your session into an unreliable pile of competing tool calls.

This article is a conceptual blueprint. It deliberately avoids low-level protocol details and focuses on the design choices that make a swarm shippable.

The Core Idea: Separate Data Plane From Control Plane

Most agent demos treat everything as chat. That works right up until you need reliability.

Swarms work when you split the system in two:

• Data plane: the “normal” work product (messages, diffs, suggestions, code).
• Control plane: the coordination traffic that makes the system safe (approvals, permissions, policies, cancellation, shutdown, health).

If you only build the data plane, you can demo a swarm. If you build the control plane, you can ship one.

The Only Stable Shape: Leader + Workers

Claude Code’s swarm model has one crucial property: a single authority for side effects.

• The leader is the policy engine. It is the one place where decisions become rules.
• The workers are execution engines. They do exploration and implementation work, but they do not get to unilaterally change the system’s permissions or bypass approvals.

Think of workers as “remote hands” with bounded autonomy. Think of the leader as the control tower.

This is not about hierarchy for its own sake. It’s about preventing the hardest class of multi-agent bugs: concurrent side effects that are locally reasonable and globally wrong.

What “Coordination” Actually Means (In Practice)

Once you have multiple agents, you stop coordinating ideas and start coordinating state.

The control plane tends to converge on a small set of flows:

1. Work assignment: leader asks a worker to investigate or implement a scoped task.
2. Plan gating: worker proposes a plan; leader approves or sends feedback; worker proceeds only after approval.
3. Permission gating: worker requests permission for a tool or capability; leader grants/denies; worker blocks safely until resolved.
4. Sandbox capability changes: network access is the common example, but the pattern generalizes.
5. Cancellation + shutdown: the leader can stop a worker cleanly; the worker acknowledges and exits predictably.
6. Health + progress: workers emit enough signals that the leader can decide whether to retry, replace, or ignore.

Notice what’s missing: “workers argue until they converge.”

In a production tool, consensus is usually the wrong mechanism. A swarm needs arbitration, not debate.

Why File Mailboxes (Or Any “Boring” Transport) Show Up

If you’re building teams/swarms, you have to answer a question that most demos skip:

Where do control-plane messages live while the leader is busy doing something else?

Claude Code uses a transport that is intentionally boring: something that can persist, be audited, and survive restarts. A filesystem mailbox is one way to do that.

The important conceptual point is not “files.”

The point is:

• control-plane messages must be durable (not lost if a process restarts)
• delivery must be replayable (so “I didn’t see it” isn’t a failure mode)
• the system should be auditable (a human can inspect what happened)

You can implement that with files, a queue, a database, or a stream. The architecture stays the same.

Concrete Excerpts (From The Client)

Below are a few short verbatim snippets from the Claude Code client bundle that show how “teams/swarms” is framed operationally.

When a worker is running under a team, the client injects an explicit team coordination system reminder (identity, resources, and messaging rules):

<system-reminder>
# Team Coordination

You are a teammate in team "{team}".
...
**Team Leader:** The team lead's name is "team-lead". Send updates and completion notifications to them.
...
**IMPORTANT:** Always refer to teammates by their NAME ..., never by UUID.
</system-reminder>

When a teammate is spawned, the leader is explicitly told the worker is waiting on mailbox instructions:

The agent is now running and will receive instructions via mailbox.

When plan-gating is enabled, the worker is hard-blocked until approval returns via the inbox:

**Important:** Do NOT proceed until you receive approval. Check your inbox for response.

And the client goes out of its way to reduce a common UX failure mode (people “polling” for messages instead of trusting the delivery mechanism):

**IMPORTANT**: Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.

Finally, the message protocol is treated as a control plane with hard requirements, not “suggestions”. For example, shutdown requests must be acknowledged with a tool call:

When you receive a shutdown request ... you **MUST** respond to approve or reject it.
Do NOT just acknowledge the request in text - you must actually call this tool.

These aren’t “motivational” prompts. They are guardrails: clear boundaries that turn a multi-agent demo into something you can actually operate.

The Golden Rule: Apply Policy Before Delivering Work

In a swarm, some messages are content and some are commands.

If a worker says “I need network access” and then immediately sends “here’s the patch,” you don’t want the patch to be applied in a world where network access wasn’t granted yet, or where permission mode is ambiguous.

So the leader needs a strict discipline:

• apply control-plane changes first (policy, permission mode, shutdown)
• then deliver data-plane messages (analysis, diffs, explanations)

That one rule prevents a huge class of “it worked once, then flaked” failures.

Where This Fits In The Overall Claude Code Architecture

Teams/swarms are not a standalone product. They sit on top of (and reuse) the same core machinery as a single-agent session:

• a permission system (tool + sandbox governance)
• tool execution with side-effect accounting
• streaming/UX as a channel for typed updates
• context management (workers must not bloat the leader’s context)
• telemetry (so you can debug coordination without guessing)

The swarm feature is mostly an integration problem: connecting those subsystems so that “parallel” does not become “chaos.”

A Useful Mental Model: Workers Are Sandboxed Contexts

One of the biggest practical wins in a leader/worker system is context isolation:

• workers can explore freely without polluting the leader’s context window
• the leader pulls back only the useful artifacts (a diff, a summary, a recommendation)

This is why swarms are often more stable than “one agent with lots of internal threads.”

Parallelism is nice, but separation is the real feature.

What You Can’t Fully Reconstruct From A Client Bundle

Even with deep reverse engineering, some parts of swarm behavior live behind server walls or rely on hosted infrastructure:

• how remote execution is authenticated/authorized
• backend enforcement of policy, quotas, and abuse protections
• any centralized routing or fleet management

You can still produce a reconstruction-grade client-side architecture: the roles, boundaries, and control-plane patterns. Just be explicit about what is client logic versus enforced server policy.

If You’re Building Your Own Swarm

If you want the “Claude Code style” outcome, optimize for:

• single authority for side effects
• explicit control plane (typed, durable, auditable)
• isolation by default (worker contexts are cheap and disposable)
• human legibility (operators should be able to answer: “what happened?”)

That’s the difference between a swarm that demos well and a swarm you can trust with real repositories.