The Orchestrator-Worker Pattern

The Pattern That Powers Multi-Agent Systems

Every working multi-agent system is built on one fundamental pattern: an orchestrator that plans and coordinates, and workers that execute bounded tasks.

In Claude Code, your main conversation is the orchestrator. It holds the big picture: the goal, the plan, the current state of progress. Subagents are the workers. Each one receives a specific, self-contained task, does its work in isolation, and reports back a summary. The orchestrator synthesizes those summaries and decides what to do next.

This separation is not just organizational. It is what makes the system scale. Workers can run in parallel. Each worker's context stays clean and focused. Failures in one worker do not contaminate the others. The orchestrator never has to wade through thousands of tokens of intermediate tool output — it only sees the summaries.

What Makes a Good Task to Delegate

Not every task belongs in a subagent. The orchestrator-worker pattern works best when delegated tasks have three properties:

Self-contained scope. The task has a clear beginning and end with a defined deliverable. "Read src/auth.py, identify all functions that handle tokens, and return a list with their line numbers and a one-sentence description of each" is a good subagent task. "Help me think through the auth system" is not — it requires iterative back-and-forth that belongs in the main session.

Independence. The task does not depend on the real-time output of another in-progress task. Tasks that depend on each other must be sequenced. Tasks that are independent can run in parallel.

Bounded context use. If a task requires reading large files or running many tool calls, doing it in the main session will eat through context fast. Delegating keeps those heavy operations inside the worker's isolated context.

Designing the Orchestration Layer

A good orchestrator prompt decomposes the work before delegating. This can be explicit (you write the decomposition yourself) or implicit (you describe the goal and Claude figures out how to split it).

Explicit decomposition:

I need to audit this codebase for three things. Use the security-auditor agent for SQL injection risks,
the dependency-checker agent for outdated packages, and the docs-auditor agent for missing docstrings.
Run all three in parallel and report back when they're done.

Implicit decomposition:

Audit this codebase for security issues, outdated dependencies, and missing documentation.
Use the appropriate agents for each.

Both approaches work. Explicit gives you more control. Implicit is faster but relies on Claude correctly mapping tasks to agent descriptions.

The Delegation Message

When Claude spawns a subagent, it writes a delegation message — the first thing the subagent sees. This message contains:

• The specific task to perform
• Any context the subagent needs (file paths, constraints, output format)
• The expected deliverable

You cannot directly control the delegation message, but you can influence it by writing clear system prompts for your agents. If your agent's system prompt says "Return a structured JSON report with severity, file path, and line number for each finding," the delegation message will include that expectation.

How Claude Decides When to Delegate

Claude reads every available agent's description field when deciding whether to spawn a subagent. The match is semantic, not keyword-based. An agent described as "reviews TypeScript for type safety issues" will be invoked when you ask for a TypeScript type check, even if you never mentioned the agent by name.

Three invocation styles exist:

• Automatic: Claude decides to delegate based on the description match and the current task
• Prompted: You say "use the X agent to do Y" — Claude invokes it immediately
• Guaranteed: You @-mention the agent by name, which guarantees invocation regardless of Claude's own judgment

For critical tasks where you need guaranteed delegation, always use the @-mention or explicit naming.

Synthesizing Results in the Orchestrator

When all workers have reported back, the orchestrator receives their summaries and synthesizes them. This synthesis is where the real value of the orchestrator layer shows up: it can compare findings across workers, identify conflicts, prioritize next actions, and decide whether to spawn additional agents or finish.

Design your worker output formats to make synthesis easy. If every worker returns a structured report with the same fields (severity, file, description), the orchestrator can aggregate them cleanly. Inconsistent output formats slow down synthesis and increase orchestrator context usage.