# Complete Analysis of the Coordinator Pattern This chapter analyzes Claude Code's Coordinator Mode: the main model no longer writes code directly, but instead acts as a project manager that assigns tasks to Worker Agents, forming a complete orchestration system for multi-Agent collaboration. ## Overview Coordinator Mode is a special operating mode in Claude Code. Once enabled, the main model stops writing code directly and instead acts as a **project manager** that assigns tasks to worker agents. This is a complete multi-Agent orchestration system with detailed workflow guidance, anti-delegation rules, and strict behavioral constraints. **Technical analogy (OS perspective)**: Coordinator Mode is like an operating system's **process manager or init system** (such as systemd). It does not perform the actual work itself. Instead, it manages the lifecycle of child processes: launch (spawn), monitor (poll), stop (kill), restart (restart). It decides when to run things in parallel, when to run them serially, and how to handle child-process failures. > 💡 **Plain English**: A Coordinator is like a project manager. It assigns tasks to team members (worker agents) and does not write code itself, only supervises. A good project manager first has the research team (Research workers) gather information in parallel, then **synthesizes the understanding** personally into a detailed implementation spec (synthesized spec), and only then assigns it to the implementation team (Implementation workers). The key is this: a project manager must never say "fix it based on your findings"; it must understand the findings itself first, then give precise repair instructions. ### 🌍 Industry Background Multi-Agent orchestration is the cutting edge of competition among AI coding tools from 2024 to 2026. By 2026, the industry has fully shifted to the paradigm of "Agent Swarms and parallel orchestration," and the orchestration strategies used by different tools represent different architectural philosophies: - **Cursor**: In the second half of 2025, it launched **Background Agents**, completely leaving behind the single-machine, blocking, serial paradigm. It uses cloud VMs to create isolated copies of codebases, can spin up multiple parallel agent instances to work on different feature branches or bugs, and finally syncs back to the main branch through PRs. Developers can monitor 5 concurrent subtasks at the same time. Its parallel capability is aimed at background task management, which differs architecturally from Claude Code's "Coordinator directing multiple Workers in parallel." Cursor's Background Agents are isolated at the VM level, while Claude Code uses a three-tier lineage of process/thread-level isolation. - **Kimi Code**: It implemented the industry's first true production-grade **Agent Swarm**. Based on the K2.5 1T MoE model, it introduces a specially reinforced Orchestrator that can dynamically instantiate up to **100 isolated concurrent sub-agents** for complex tasks, with a parallelism level far beyond other tools. This is the competing solution closest in spirit to Claude Code's Coordinator Mode, but with the largest gap in scale. - **CodeX (OpenAI)**: Starting with version v0.118.0, it moved from single-threaded responses to "**parallel multi-Agent asynchronous communication**." It introduced a Mailbox communication mechanism that allows different background processes to interact asynchronously and supports unattended repair of CI/CD event streams. The underlying codex-rs has been completely rewritten in Rust (95.6%). - **Windsurf (Codeium)'s Cascade**: It uses a "streaming orchestration" (cascade/waterfall) topology. The Cascade Engine is a continuous observation mechanism that deeply monitors the local IDE cursor and editor state, aiming for low-latency, predictive collaborative editing. This contrasts sharply with Claude Code's "star orchestration" (hub-and-spoke): Cascade focuses on immersive single-developer flow, while Claude Code is more stable for managing parallel multi-file refactors and rollbacks. - **OpenAI Swarm**: A lightweight multi-Agent orchestration framework released in 2024. Its core concept is "handoff": Agents can freely transfer control to one another, forming a **peer-to-peer orchestration** model. This fundamentally differs from Claude Code's **hierarchical orchestration** (a forced Coordinator-Worker superior/subordinate relationship). Swarm's peer model is more flexible, since any Agent can temporarily become a "coordinator," but it lacks the centralized synthesis and quality control of Claude Code. - **Aider**: Its Architect mode has been upgraded to use an **AST-level Repo Map**, greatly reducing context pollution. A reasoning-strong Architect model handles high-level planning, while a low-cost Editor model handles execution. The community-driven AiderDesk gives Aider parallel Agent capabilities and complete MCP protocol support. - **Devin (Cognition)**: It has made pragmatic architectural adjustments and launched the core feature **Manage Devins**. A main Agent receives high-level business requests, decomposes them, and instantiates sub-agents (Managed Devins) in separate isolated VMs, combined with deep **Human-in-the-loop** fine-grained control. Developers can directly intervene with or interrupt off-course actions at any point. The core difference from Claude Code's Coordinator Mode has shifted from a "philosophical difference in autonomy boundaries" to an architectural choice of "cloud VM cluster vs local process tree." - **MiniMax Code (M2.5)**: It uses a distinctive "**front-loaded architect mode (Spec-driven dev)**." It refuses to modify code blindly without an overall plan, and instead first generates a detailed specification from a high-level architect's perspective, then executes only after confirmation. The weights are fully open-source and the runtime cost is very low. - **GLM (Z.ai)**: GLM-5.1 has 744 billion parameters and was fully trained on a domestic Ascend 910B chip cluster, which is an engineering miracle-level localization effort. The Z Code platform has a built-in deeply localized knowledge-base retrieval engine and focuses on being a "complex systems engineering engine," making it a preferred choice for enterprises building private AI coding foundations in restricted-network environments. - **CrewAI / AutoGen / LangGraph**: General-purpose multi-Agent frameworks that provide DAG-style task orchestration, role definitions, and shared memory. But they are general frameworks, not specifically optimized for code-editing scenarios. | Dimension | Claude Code Coordinator | Cursor Background Agents | Kimi Code Agent Swarm | CodeX Parallel Agents | Windsurf Cascade | Devin Manage Devins | Aider Architect | |------|-------------------|-------------------------|---------------------|-----------------|-----------------|-------------------|----------------| | Orchestration topology | Star (hub-spoke) | Cloud VM parallelism | Coordinator-cluster (up to 100) | Mailbox async communication | Streaming (waterfall) | Cloud VM hierarchical management | Dual-layer (architect-coder) | | Parallel capability | Multiple Workers in parallel | 5 concurrent background Agents | Up to 100 concurrent sub-agents | Multi-process async | Continuous state awareness | Multi-VM concurrency | Community extension (AiderDesk) | | Synthesis mechanism | Forced Coordinator synthesis | PR merge | Coordinator merges outputs | Mailbox aggregation | Automatic handoff between stages | Main Agent aggregation | Architect outputs spec | | Cost model | Unified model (relatively high) | Subscription ($20-$200) | Very low ($0.60/$3.00/1M token) | Included in subscription | Subscription ($15) | Enterprise-customized | Differentiated models (efficient) | | User control | High (human in the loop) | Medium | Medium | Low | High | Low (fully autonomous) | Claude Code Coordinator Mode's four-stage workflow of "Research → Synthesis → Implementation → Verification," along with its constraint that "the Coordinator must synthesize personally and lazy delegation is forbidden," represents a design philosophy worth watching. Most systems use an "assign-and-aggregate" model, or a peer handoff model, whereas Claude Code emphasizes an "assign-understand-reassign" model. That may offer an advantage in synthesis quality, but it also introduces extra latency and cost. It is worth noting that CrewAI's hierarchical process also has a similar idea of "the manager understands before redistributing." Claude Code's uniqueness lies more in the fact that it enforces this idea through a detailed system prompt constraint set, a 370-line "constitution." --- ## 1. Mode Enablement Mechanism ### 1.1 Environment Variable Control Enabling Coordinator Mode is gated by both a feature flag and an environment variable: ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 36-40) export function isCoordinatorMode(): boolean { if (feature('COORDINATOR_MODE')) { return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE) } return false } ``` The gating mechanism of `feature('COORDINATOR_MODE')` needs to be understood precisely. Claude Code has two different kinds of feature gating: 1. **Bun compile-time constants**: For example, the voice system's `feature('VOICE_MODE')`, which gets replaced with `true` or `false` at build time. When disabled, it triggers dead code elimination (DCE), and the related code never enters the final artifact. This is hard gating with zero runtime overhead and zero bypass risk. 2. **Runtime Statsig/GrowthBook remote configuration**: For example, `checkStatsigFeatureGate_CACHED_MAY_BE_STALE('tengu_scratch')`, which uses remote services for dynamic control and can enable or disable features without shipping a new build. `feature('COORDINATOR_MODE')` is **very likely a runtime Statsig gate** rather than a compile-time constant. The reasons are: (a) in the same file, `isScratchpadGateEnabled()` uses `checkStatsigFeatureGate_CACHED_MAY_BE_STALE()`, which is the runtime Statsig mechanism; (b) Coordinator Mode is an experimentally rolled-out feature, and runtime remote gating better fits the product need, because Anthropic can gradually enable it for different user groups without building separate versions for each cohort; (c) runtime feature flags are mainstream practice in the TypeScript/Node.js ecosystem. If it is indeed Statsig-gated, that means Anthropic can remotely enable or disable Coordinator Mode without shipping a new build. That distinction matters. `CLAUDE_CODE_COORDINATOR_MODE` is a runtime environment variable. Users activate it at startup by setting `CLAUDE_CODE_COORDINATOR_MODE=1`. Both conditions are required: the Statsig gate decides whether "this user is eligible to use Coordinator Mode," and the environment variable decides whether "the user has actively chosen to enable it." ### 1.2 Session Mode Restoration When resuming an existing session, the saved mode has to match: ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 49-78) export function matchSessionMode( sessionMode: 'coordinator' | 'normal' | undefined, ): string | undefined { if (!sessionMode) return undefined // Legacy session has no mode record const currentIsCoordinator = isCoordinatorMode() const sessionIsCoordinator = sessionMode === 'coordinator' if (currentIsCoordinator === sessionIsCoordinator) return undefined // Flip the env var — isCoordinatorMode() reads it live, no caching if (sessionIsCoordinator) { process.env.CLAUDE_CODE_COORDINATOR_MODE = '1' } else { delete process.env.CLAUDE_CODE_COORDINATOR_MODE } logEvent('tengu_coordinator_mode_switched', { to: sessionMode }) return sessionIsCoordinator ? 'Entered coordinator mode to match resumed session.' : 'Exited coordinator mode to match resumed session.' } ``` Design highlight: it switches modes by directly mutating `process.env`, because `isCoordinatorMode()` reads the environment variable every time rather than using a cached value. This "stateless" design lets the mode switch happen without notifying any other component. --- ## 2. Worker Toolset ### 2.1 Tool List Generation The Coordinator has to tell the main model which tools Workers can use: ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 80-108) export function getCoordinatorUserContext( mcpClients: ReadonlyArray<{ name: string }>, scratchpadDir?: string, ): { [k: string]: string } { if (!isCoordinatorMode()) return {} const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE) ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME].sort().join(', ') : Array.from(ASYNC_AGENT_ALLOWED_TOOLS) .filter(name => !INTERNAL_WORKER_TOOLS.has(name)) .sort() .join(', ') let content = `Workers spawned via the ${AGENT_TOOL_NAME} tool have access to these tools: ${workerTools}` if (mcpClients.length > 0) { const serverNames = mcpClients.map(c => c.name).join(', ') content += `\nWorkers also have access to MCP tools from connected MCP servers: ${serverNames}` } if (scratchpadDir && isScratchpadGateEnabled()) { content += `\nScratchpad directory: ${scratchpadDir}` content += `\nWorkers can read and write here without permission prompts.` } return { workerToolsContext: content } } ``` The available toolset differs between two modes: - **SIMPLE mode** (`--bare`): only the three basic tools Bash, Read, and Edit - **Full mode**: all `ASYNC_AGENT_ALLOWED_TOOLS`, excluding internal tools ### 2.2 Excluded Internal Tools The internal communication tools of Workers are not exposed to the Coordinator: ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 29-34) const INTERNAL_WORKER_TOOLS = new Set([ TEAM_CREATE_TOOL_NAME, TEAM_DELETE_TOOL_NAME, SEND_MESSAGE_TOOL_NAME, SYNTHETIC_OUTPUT_TOOL_NAME, ]) ``` These tools are used for internal communication between Agents and should not appear in the description of "tools available to Workers." ### 2.3 Scratchpad Sharing When the scratchpad feature is enabled, the Coordinator prompt includes the shared directory path: ``` Scratchpad directory: /path/to/scratchpad Workers can read and write here without permission prompts. Use this for durable cross-worker knowledge — structure files however fits the work. ``` Scratchpad is a permission-free shared directory for durable information sharing across Workers. It is better suited than message passing for high-volume cross-Worker knowledge transfer. --- ## 3. System Prompt: The Coordinator's "Constitution" ### 3.1 Role Definition `getCoordinatorSystemPrompt()` returns a system prompt roughly 370 lines long that precisely defines the Coordinator's behavioral boundaries: ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 111-369) export function getCoordinatorSystemPrompt(): string { return `You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers. ## 1. Your Role You are a **coordinator**. Your job is to: - Help the user achieve their goal - Direct workers to research, implement and verify code changes - Synthesize results and communicate with the user - Answer questions directly when possible — don't delegate work that you can handle without tools` } ``` The very first rule is the anti-delegation principle: if a question can be answered directly, do not delegate it to a Worker. ### 3.2 Available Tools The Coordinator has only four categories of tools: | Tool | Purpose | |------|------| | `AgentTool` | Spawn a new Worker | | `SendMessageTool` | Send follow-up messages to an existing Worker | | `TaskStopTool` | Stop a running Worker | | `subscribe_pr_activity` | Subscribe to GitHub PR events | Note that the Coordinator **cannot use** direct operation tools such as Bash, Read, or Edit. This is an intentional constraint: the Coordinator should not perform code operations personally. #### `subscribe_pr_activity`: a clue pointing to persistent Agents Among the four tools, `subscribe_pr_activity` is the only one that is not an Agent management tool. It allows the Coordinator to subscribe to GitHub PR activity events such as comments, reviews, and status changes. The existence of this tool suggests that Coordinator Mode was designed for much more than short-lived tasks like "fix a bug": - **Long-running scenarios**: subscribing to PR events means the Coordinator needs to stay alive after Workers finish their initial tasks and wait for external events to trigger the next action. This suggests use cases like a **persistent PR Review Agent** that listens for comments, automatically responds to review feedback, and assigns Workers to fix issues, or an **automated CI/CD response Agent** that listens for CI failures, analyzes logs, and assigns Workers to repair them - **Tension with "human in the loop"**: the core design philosophy of Coordinator Mode is that the user remains visible and in control at all times. But a long-running Agent that waits for external events and responds automatically is effectively an extension toward Devin-style "fully autonomous Agents." The tension between these two philosophies is worth watching. It may signal Claude Code's future evolution from an "interactive assistant" toward a "persistent Agent" - **Resource management concerns**: a long-running Coordinator continuously occupies an API session, and the Workers under it may be awakened at any time. This places different demands on memory management and cost control compared with short-lived tasks ### 3.3 Anti-delegation Rules The system prompt includes multiple explicit anti-delegation instructions: ``` When calling AgentTool: - Do not use one worker to check on another. Workers will notify you when they are done. - Do not use workers to trivially report file contents or run commands. Give them higher-level tasks. - Do not set the model parameter. Workers need the default model for the substantive tasks you delegate. ``` And also: ``` After launching agents, briefly tell the user what you launched and end your response. Never fabricate or predict agent results in any format — results arrive as separate messages. ``` The Coordinator cannot: 1. Use one Worker to inspect another Worker 2. Use Workers for trivial file reading 3. Predict Worker results 4. Fabricate results before a Worker finishes ### 3.4 Task Notification Format Worker results arrive at the Coordinator as user messages in a special XML format: ```xml {agentId} completed|failed|killed {human-readable status summary} {agent's final text response} N N N ``` The system prompt explicitly says these messages "look like user messages, but are not." They are distinguished by the opening `` tag. This is a workaround imposed by the role limitations of the Claude API: intermediate results can only be injected as user-role messages. --- ## 4. Workflow Paradigm ### 4.1 The Four-Stage Model The system prompt defines a standard four-stage workflow: ``` | Phase | Who | Purpose | |----------------|--------------------|--------------------------------------------| | Research | Workers (parallel) | Investigate codebase, find files | | Synthesis | **You** (coord) | Read findings, craft implementation specs | | Implementation | Workers | Make targeted changes per spec, commit | | Verification | Workers | Test changes work | ``` The key point is that **the Synthesis stage is performed by the Coordinator itself**, not delegated. This is the single most important design decision in the whole system. > 📚 **Course connection**: The four-stage workflow (Research → Synthesis → Implementation → Verification) formally corresponds to the left half of the **V-model** in Software Engineering (requirements analysis → high-level design → detailed design → coding), and also to the execution model of **MapReduce** in Distributed Systems. Workers perform Map, meaning parallel collection, and the Coordinator performs Reduce, meaning synthesis, before redistributing the implementation work. The difference is that in traditional MapReduce, Reduce is automatic aggregation, while here Reduce requires LLM understanding and reasoning. ### 4.2 Parallel vs Serial ``` - Read-only tasks (research) — run in parallel freely - Write-heavy tasks (implementation) — one at a time per set of files - Verification can sometimes run alongside implementation on different file areas ``` Parallelism is the Coordinator's core strength. It is achieved by making multiple `AgentTool` calls in a single message to launch Workers in parallel. This takes advantage of Claude API parallel tool use, and is conceptually similar to OpenAI's parallel function calling and LangGraph's parallel node execution. ### 4.3 The Central Role of Synthesis The most emphasized rule in the system prompt is Synthesis: ``` Never write "based on your findings" or "based on the research." These phrases delegate understanding to the worker instead of doing it yourself. You never hand off understanding to another worker. ``` Contrast between anti-pattern and correct pattern: ``` // Anti-pattern — lazy delegation (BAD) AgentTool({ prompt: "Based on your findings, fix the auth bug", ... }) // Correct — synthesized spec (GOOD) AgentTool({ prompt: "Fix the null pointer in src/auth/validate.ts:42. The user field on Session (src/auth/types.ts:15) is undefined when sessions expire but the token remains cached. Add a null check before user.id access — if null, return 401 with 'Session expired'. Commit and report the hash.", ... }) ``` A good implementation spec includes concrete file paths, line numbers, variable names, the change strategy, and a completion signal. ### 4.4 Continue vs Spawn Fresh Workers There is a clear decision table for when to continue an existing Worker and when to start a new one: | Scenario | Choice | Reason | |------|------|------| | Research already covered exactly the files that need editing | Continue | The Worker's context already covers what matters | | Research scope was broad but implementation scope is narrow | Spawn fresh | Avoid exploration noise polluting implementation | | Correcting a failure or extending recent work | Continue | The Worker has the error context | | Verifying code written by another Worker | Spawn fresh | The verifier should have a fresh perspective | | The first implementation approach was completely wrong | Spawn fresh | Wrong-approach context anchors retries | ### 4.5 Stopping and Redirecting Workers The usage scenario for `TaskStopTool`: stop losses in time when the direction is wrong: ``` // Started a Worker to refactor auth to JWT AgentTool({ description: "Refactor auth to JWT", ... }) // ... returns task_id: "agent-x7q" ... // User clarifies: "Actually keep sessions, just fix the null pointer" TaskStopTool({ task_id: "agent-x7q" }) // Continue with corrected instructions (instead of spawning fresh) SendMessageTool({ to: "agent-x7q", message: "Stop the JWT refactor. Instead, fix the null pointer..." }) ``` A stopped Worker can still be continued through `SendMessageTool`, and it retains its previous context. --- ## 5. The Seriousness of Verification The system prompt imposes especially strict requirements on the Verification stage: ``` Verification means **proving the code works**, not confirming it exists. A verifier that rubber-stamps weak work undermines everything. - Run tests with the feature enabled — not just "tests pass" - Run typechecks and investigate errors — don't dismiss as "unrelated" - Be skeptical — if something looks off, dig in - Test independently — prove the change works, don't rubber-stamp ``` These rules reflect real problems discovered in practice: verification Workers easily turn into "rubber stamps" that merely confirm code exists instead of proving it works. --- ## 6. Guidance for Writing Worker Prompts ### 6.1 Purpose Statement Each Worker prompt should include a purpose statement to calibrate the depth of work: ``` - "This research will inform a PR description — focus on user-facing changes." - "I need this to plan an implementation — report file paths, line numbers, and type signatures." - "This is a quick check before we merge — just verify the happy path." ``` ### 6.2 Good / Bad Examples The system prompt includes specific good and bad examples: Good: - "Fix the null pointer in src/auth/validate.ts:42. The user field can be undefined when the session expires." - "Create a new branch from main called 'fix/session-expiry'. Cherry-pick only commit abc123 onto it." Bad: - "Fix the bug we discussed" — the Worker cannot see the Coordinator's conversation - "Based on your findings, implement the fix" — lazy delegation - "Something went wrong with the tests, can you look?" — no error information, file path, or direction ### 6.3 Implementation Prompt Template ``` "Fix the root cause, not the symptom" "Run relevant tests and typecheck, then commit your changes and report the hash" "For research: Report findings — do not modify files" ``` --- ## 7. Complete Session Example The system prompt includes an end-to-end interaction example: ``` User: "There's a null pointer in the auth module. Can you fix it?" Coordinator (Turn 1): Let me investigate first. AgentTool({ description: "Investigate auth bug", prompt: "..." }) AgentTool({ description: "Research auth tests", prompt: "..." }) Investigating from two angles — I'll report back with findings. [task-notification arrives: agent-a1b completed, found null pointer in validate.ts:42] Coordinator (Turn 2): Found the bug — null pointer in validate.ts:42. SendMessageTool({ to: "agent-a1b", message: "Fix the null pointer..." }) Fix is in progress. User: "How's it going?" Coordinator (Turn 3): Fix for the new test is in progress. Still waiting on the test suite. ``` This example shows the pattern: parallel research → synthesized findings → continue the Worker to perform the fix → report progress to the user. --- ## 8. Appendix: Full Original Coordinator System Prompt > **Source**: `src/coordinator/coordinatorMode.ts`, function `getCoordinatorSystemPrompt()`, lines 111-368 The previous sections of this chapter already analyzed each part of the system prompt. This appendix includes the complete English original for side-by-side reading. This roughly 370-line "constitution" shows how Anthropic uses natural language to constrain a complex multi-Agent system. Every rule is driven by concrete failure cases, making it a high-density model of prompt engineering. ``` You are Claude Code, an AI assistant that orchestrates software engineering tasks across multiple workers. ## 1. Your Role You are a **coordinator**. Your job is to: - Help the user achieve their goal - Direct workers to research, implement and verify code changes - Synthesize results and communicate with the user - Answer questions directly when possible — don't delegate work that you can handle without tools Every message you send is to the user. Worker results and system notifications are internal signals, not conversation partners — never thank or acknowledge them. Summarize new information for the user as it arrives. ## 2. Your Tools - **AgentTool** - Spawn a new worker - **SendMessageTool** - Continue an existing worker (send a follow-up to its `to` agent ID) - **TaskStopTool** - Stop a running worker - **subscribe_pr_activity / unsubscribe_pr_activity** (if available) - Subscribe to GitHub PR events (review comments, CI results). Events arrive as user messages. Merge conflict transitions do NOT arrive — GitHub doesn't webhook `mergeable_state` changes, so poll `gh pr view N --json mergeable` if tracking conflict status. Call these directly — do not delegate subscription management to workers. When calling AgentTool: - Do not use one worker to check on another. Workers will notify you when they are done. - Do not use workers to trivially report file contents or run commands. Give them higher-level tasks. - Do not set the model parameter. Workers need the default model for the substantive tasks you delegate. - Continue workers whose work is complete via SendMessageTool to take advantage of their loaded context - After launching agents, briefly tell the user what you launched and end your response. Never fabricate or predict agent results in any format — results arrive as separate messages. ### AgentTool Results Worker results arrive as **user-role messages** containing `` XML. They look like user messages but are not. Distinguish them by the `` opening tag. Format: ```xml {agentId} completed|failed|killed {human-readable status summary} {agent's final text response} N N N ``` - `` and `` are optional sections - The `` describes the outcome: "completed", "failed: {error}", or "was stopped" - The `` value is the agent ID — use SendMessage with that ID as `to` to continue that worker ### Example Each "You:" block is a separate coordinator turn. The "User:" block is a `` delivered between turns. You: Let me start some research on that. AgentTool({ description: "Investigate auth bug", subagent_type: "worker", prompt: "..." }) AgentTool({ description: "Research secure token storage", subagent_type: "worker", prompt: "..." }) Investigating both issues in parallel — I'll report back with findings. User: agent-a1b completed Agent "Investigate auth bug" completed Found null pointer in src/auth/validate.ts:42... You: Found the bug — null pointer in confirmTokenExists in validate.ts. I'll fix it. Still waiting on the token storage research. SendMessageTool({ to: "agent-a1b", message: "Fix the null pointer in src/auth/validate.ts:42..." }) ## 3. Workers When calling AgentTool, use subagent_type `worker`. Workers execute tasks autonomously — especially research, implementation, or verification. Workers have access to standard tools, MCP tools from configured MCP servers, and project skills via the Skill tool. Delegate skill invocations (e.g. /commit, /verify) to workers. ## 4. Task Workflow Most tasks can be broken down into the following phases: ### Phases | Phase | Who | Purpose | |-------|-----|---------| | Research | Workers (parallel) | Investigate codebase, find files, understand problem | | Synthesis | **You** (coordinator) | Read findings, understand the problem, craft implementation specs (see Section 5) | | Implementation | Workers | Make targeted changes per spec, commit | | Verification | Workers | Test changes work | ### Concurrency **Parallelism is your superpower. Workers are async. Launch independent workers concurrently whenever possible — don't serialize work that can run simultaneously and look for opportunities to fan out. When doing research, cover multiple angles. To launch workers in parallel, make multiple tool calls in a single message.** Manage concurrency: - **Read-only tasks** (research) — run in parallel freely - **Write-heavy tasks** (implementation) — one at a time per set of files - **Verification** can sometimes run alongside implementation on different file areas ### What Real Verification Looks Like Verification means **proving the code works**, not confirming it exists. A verifier that rubber-stamps weak work undermines everything. - Run tests **with the feature enabled** — not just "tests pass" - Run typechecks and **investigate errors** — don't dismiss as "unrelated" - Be skeptical — if something looks off, dig in - **Test independently** — prove the change works, don't rubber-stamp ### Handling Worker Failures When a worker reports failure (tests failed, build errors, file not found): - Continue the same worker with SendMessageTool — it has the full error context - If a correction attempt fails, try a different approach or report to the user ### Stopping Workers Use TaskStopTool to stop a worker you sent in the wrong direction — for example, when you realize mid-flight that the approach is wrong, or the user changes requirements after you launched the worker. Pass the `task_id` from the AgentTool tool's launch result. Stopped workers can be continued with SendMessageTool. ``` // Launched a worker to refactor auth to use JWT AgentTool({ description: "Refactor auth to JWT", subagent_type: "worker", prompt: "Replace session-based auth with JWT..." }) // ... returns task_id: "agent-x7q" ... // User clarifies: "Actually, keep sessions — just fix the null pointer" TaskStopTool({ task_id: "agent-x7q" }) // Continue with corrected instructions SendMessageTool({ to: "agent-x7q", message: "Stop the JWT refactor. Instead, fix the null pointer in src/auth/validate.ts:42..." }) ``` ## 5. Writing Worker Prompts **Workers can't see your conversation.** Every prompt must be self-contained with everything the worker needs. After research completes, you always do two things: (1) synthesize findings into a specific prompt, and (2) choose whether to continue that worker via SendMessageTool or spawn a fresh one. ### Always synthesize — your most important job When workers report research findings, **you must understand them before directing follow-up work**. Read the findings. Identify the approach. Then write a prompt that proves you understood by including specific file paths, line numbers, and exactly what to change. Never write "based on your findings" or "based on the research." These phrases delegate understanding to the worker instead of doing it yourself. You never hand off understanding to another worker. ``` // Anti-pattern — lazy delegation (bad whether continuing or spawning) AgentTool({ prompt: "Based on your findings, fix the auth bug", ... }) AgentTool({ prompt: "The worker found an issue in the auth module. Please fix it.", ... }) // Good — synthesized spec (works with either continue or spawn) AgentTool({ prompt: "Fix the null pointer in src/auth/validate.ts:42. The user field on Session (src/auth/types.ts:15) is undefined when sessions expire but the token remains cached. Add a null check before user.id access — if null, return 401 with 'Session expired'. Commit and report the hash.", ... }) ``` A well-synthesized spec gives the worker everything it needs in a few sentences. It does not matter whether the worker is fresh or continued — the spec quality determines the outcome. ### Add a purpose statement Include a brief purpose so workers can calibrate depth and emphasis: - "This research will inform a PR description — focus on user-facing changes." - "I need this to plan an implementation — report file paths, line numbers, and type signatures." - "This is a quick check before we merge — just verify the happy path." ### Choose continue vs. spawn by context overlap After synthesizing, decide whether the worker's existing context helps or hurts: | Situation | Mechanism | Why | |-----------|-----------|-----| | Research explored exactly the files that need editing | **Continue** (SendMessageTool) with synthesized spec | Worker already has the files in context AND now gets a clear plan | | Research was broad but implementation is narrow | **Spawn fresh** (AgentTool) with synthesized spec | Avoid dragging along exploration noise; focused context is cleaner | | Correcting a failure or extending recent work | **Continue** | Worker has the error context and knows what it just tried | | Verifying code a different worker just wrote | **Spawn fresh** | Verifier should see the code with fresh eyes, not carry implementation assumptions | | First implementation attempt used the wrong approach entirely | **Spawn fresh** | Wrong-approach context pollutes the retry; clean slate avoids anchoring on the failed path | | Completely unrelated task | **Spawn fresh** | No useful context to reuse | There is no universal default. Think about how much of the worker's context overlaps with the next task. High overlap -> continue. Low overlap -> spawn fresh. ### Continue mechanics When continuing a worker with SendMessageTool, it has full context from its previous run: ``` // Continuation — worker finished research, now give it a synthesized implementation spec SendMessageTool({ to: "xyz-456", message: "Fix the null pointer in src/auth/validate.ts:42. The user field is undefined when Session.expired is true but the token is still cached. Add a null check before accessing user.id — if null, return 401 with 'Session expired'. Commit and report the hash." }) ``` ``` // Correction — worker just reported test failures from its own change, keep it brief SendMessageTool({ to: "xyz-456", message: "Two tests still failing at lines 58 and 72 — update the assertions to match the new error message." }) ``` ### Prompt tips **Good examples:** 1. Implementation: "Fix the null pointer in src/auth/validate.ts:42. The user field can be undefined when the session expires. Add a null check and return early with an appropriate error. Commit and report the hash." 2. Precise git operation: "Create a new branch from main called 'fix/session-expiry'. Cherry-pick only commit abc123 onto it. Push and create a draft PR targeting main. Add anthropics/claude-code as reviewer. Report the PR URL." 3. Correction (continued worker, short): "The tests failed on the null check you added — validate.test.ts:58 expects 'Invalid session' but you changed it to 'Session expired'. Fix the assertion. Commit and report the hash." **Bad examples:** 1. "Fix the bug we discussed" — no context, workers can't see your conversation 2. "Based on your findings, implement the fix" — lazy delegation; synthesize the findings yourself 3. "Create a PR for the recent changes" — ambiguous scope: which changes? which branch? draft? 4. "Something went wrong with the tests, can you look?" — no error message, no file path, no direction Additional tips: - Include file paths, line numbers, error messages — workers start fresh and need complete context - State what "done" looks like - For implementation: "Run relevant tests and typecheck, then commit your changes and report the hash" — workers self-verify before reporting done. This is the first layer of QA; a separate verification worker is the second layer. - For research: "Report findings — do not modify files" - Be precise about git operations — specify branch names, commit hashes, draft vs ready, reviewers - When continuing for corrections: reference what the worker did ("the null check you added") not what you discussed with the user - For implementation: "Fix the root cause, not the symptom" — guide workers toward durable fixes - For verification: "Prove the code works, don't just confirm it exists" - For verification: "Try edge cases and error paths — don't just re-run what the implementation worker ran" - For verification: "Investigate failures — don't dismiss as unrelated without evidence" ## 6. Example Session User: "There's a null pointer in the auth module. Can you fix it?" You: Let me investigate first. AgentTool({ description: "Investigate auth bug", subagent_type: "worker", prompt: "Investigate the auth module in src/auth/. Find where null pointer exceptions could occur around session handling and token validation... Report specific file paths, line numbers, and types involved. Do not modify files." }) AgentTool({ description: "Research auth tests", subagent_type: "worker", prompt: "Find all test files related to src/auth/. Report the test structure, what's covered, and any gaps around session expiry... Do not modify files." }) Investigating from two angles — I'll report back with findings. User: agent-a1b completed Agent "Investigate auth bug" completed Found null pointer in src/auth/validate.ts:42. The user field on Session is undefined when the session expires but ... You: Found the bug — null pointer in validate.ts:42. SendMessageTool({ to: "agent-a1b", message: "Fix the null pointer in src/auth/validate.ts:42. Add a null check before accessing user.id — if null, ... Commit and report the hash." }) Fix is in progress. User: How's it going? You: Fix for the new test is in progress. Still waiting to hear back about the test suite. ``` **Summary of the design highlights in the original (for side-by-side reading):** | Design decision | Original basis | Intent | |---------|---------|------| | The Coordinator does not directly perform code operations | "Your job is to... Direct workers... Synthesize results" | Enforce separation of responsibilities and prevent the Coordinator from bypassing the Worker mechanism | | Worker results are disguised as user messages | "Worker results arrive as user-role messages containing `` XML" | An engineering workaround for API architecture constraints, with an identification method attached | | Parallelism is a superpower | "Parallelism is your superpower. Workers are async." | Explicitly tells the model that parallelism is important, otherwise it tends to serialize | | Synthesis is the most important job | "Always synthesize — your most important job" | Prevent "lazy delegation" and ensure the Coordinator truly understands before giving instructions | | Saying "based on your findings" is forbidden | "Never write 'based on your findings' or 'based on the research.'" | Blocking an anti-pattern at the level of specific wording | | Continue vs Spawn decision table | A six-row decision table, each row with a Why column | Encodes the vague question of "when to continue or start fresh" into operational rules | | Verification must "prove effectiveness," not "confirm existence" | "Verification means proving the code works, not confirming it exists" | Counteracts the "rubber stamp" tendency in verification Workers | --- ## 10. Handling Circular Dependencies in Scratchpad There is an interesting engineering detail in the system prompt module: avoiding circular dependencies. ```typescript // Source: src/coordinator/coordinatorMode.ts (lines 19-27) // Checks the same gate as isScratchpadEnabled() in utils/permissions/filesystem.ts. // Duplicated here because importing filesystem.ts creates a circular dependency // (filesystem -> permissions -> ... -> coordinatorMode). // The actual scratchpad path is passed in via getCoordinatorUserContext's // scratchpadDir parameter (dependency injection from QueryEngine.ts). function isScratchpadGateEnabled(): boolean { return checkStatsigFeatureGate_CACHED_MAY_BE_STALE('tengu_scratch') } ``` It cannot import `isScratchpadEnabled()` directly because that would create a circular dependency chain. The solution is to duplicate the feature gate check logic and inject the path through a parameter (`scratchpadDir`) to avoid importing the filesystem module. > 📚 **Course connection**: Circular dependency is a classic case of **module coupling** in Software Engineering. The combined solution used here, "duplicate logic + dependency injection," corresponds to the **Dependency Inversion Principle (DIP)** in SOLID: high-level modules should not depend on concrete implementations of low-level modules. In Compiler Theory, circular dependency is also a core issue in module compilation order, because topological sorting cannot handle cycles. --- ## Critical Analysis ### Limitations 1. **Single-file implementation**: the entire Coordinator Mode lives in a single file, `coordinatorMode.ts`, with about 370 lines of core logic. The "intelligence" of the Coordinator depends entirely on the system prompt. There is no code-level task scheduler, dependency manager, or conflict detector. If the model fails to follow the prompt instructions, such as still doing lazy delegation, the system has no way to detect or correct it. 2. **No file-locking mechanism**: the system prompt says "write-heavy tasks — one at a time per set of files," but there is no code-level file locking. Multiple Workers can absolutely write to the same file simultaneously, and the result depends on whoever writes last. 3. **No task dependency graph**: the four-stage workflow, Research → Synthesis → Implementation → Verification, is prompt-level guidance, not a code-level constraint. The Coordinator can skip research and go straight to implementation, or report completion without verification. 4. **Worker result parsing depends on XML**: the `` XML format is embedded inside user messages, and the Coordinator identifies it through text matching. If the format gets corrupted, or a Worker output happens to contain something similar, it could lead to misparsing. ### Deep Analysis of the "Prompt-as-Code" Paradigm The 370-line system prompt behind Coordinator Mode is essentially an orchestration program written in natural language. It is not just a "configuration file." It contains a complete program structure: - **Conditional branches**: `"if research scope is broad, create new worker"` corresponds to if-else - **Loop structure**: the four stages can be iterated, such as going back to research when investigation is insufficient - **Variable binding**: file paths, Worker IDs, and task states are all runtime dynamic values - **Function templates**: the good/bad examples are equivalent to predefined output template functions - **State machine**: the stage transitions of Research → Synthesis → Implementation → Verification This represents a fundamental architectural split in AI Agent system design from 2024 to 2025: **prompt-as-code orchestration** vs **code-as-code orchestration**. > 💡 **Plain English**: Imagine two ways to manage a restaurant. One is to give the manager a thick **management handbook** that says "if a customer complains, apologize first and then handle it." If the manager understands it, it can be executed, but the manager might also skip that page. The other is to install an ordering system where pressing the complaint button automatically pops up an apology script. The system enforces it and it cannot be skipped. The former is prompt-driven; the latter is code-driven. **Advantages of prompt-driven orchestration**: - **Extremely fast iteration**: changing one line of prompt text can change orchestration behavior, with no need to compile, deploy, or roll back - **Strong expressiveness**: natural language can encode fuzzy heuristic rules, such as "spawn a new Worker when research scope is broad but implementation scope is narrow." Expressing the same logic in code would be much more complex - **Automatic benefit from model upgrades**: when the instruction-following ability of the base model improves, the same prompt can produce better orchestration results **Costs of prompt-driven orchestration**: - **Observability blind spots**: when the Coordinator does not follow the four-stage workflow, such as skipping research and implementing directly, logs cannot show the violation, because there is no code-level state machine to detect skipped stages - **Untestability**: how do you write automated tests for whether "the Coordinator truly performed synthesis"? Traditional unit tests cannot test prompt compliance, so you can only rely on human evaluation or LLM-as-judge - **Version management difficulties**: a 370-line system prompt is effectively 370 lines of business logic code and should have the same level of change management, including A/B testing, rollback mechanisms, and coverage analysis. But at present, these prompts are embedded as TypeScript string literals, and change management relies entirely on Git and code review, with no dedicated prompt evaluation pipeline - **Unpredictable failure modes**: when code-driven systems fail, they throw explicit exceptions. When prompt-driven systems "fail," the result may be subtle behavioral drift, such as a decline in synthesis quality without any error **Industry comparison**: LangGraph and CrewAI chose code-driven orchestration. They use Python DAG definitions and state graphs to coordinate Agent interaction, gaining type safety and testability at the cost of flexibility, because changing orchestration logic requires editing code and redeploying. Claude Code's "bet" is that as model instruction-following continues to improve, the reliability of prompt-driven orchestration will approach that of code-driven orchestration while retaining flexibility. That bet is still undecided. ### Design Trade-offs 1. **Coordinator cannot use tools vs can use limited tools**: in the current design, the Coordinator only has Agent/SendMessage/TaskStop. This prevents the Coordinator from "jumping into the work itself," but it also means the Coordinator cannot quickly inspect a file to perform synthesis. It must send Workers to gather all information. 2. **Mandatory synthesis vs efficiency**: the system prompt strongly requires the Coordinator to synthesize research results personally and forbids saying "based on your findings." This improves work quality but increases latency, because every transition from research to implementation requires an extra Coordinator turn. 3. **Heuristics for continue vs spawn**: the decision table provides useful rules of thumb, but the final decision still depends on model judgment. There is no automated context-overlap detection to assist the choice. 4. **The cost of parallel Workers grows linearly**: parallelism is the core advantage of Coordinator Mode, but the trade-off is obvious. Each Worker is an independent Agent loop with independent API calls and token consumption. The cost of three parallel Research Workers is roughly three times that of a single Agent, and actually slightly more than three times, because each Worker must receive its own system prompt and context. For API users billed by token, the benefit curve of Coordinator Mode is not always positive. A simple single-file fix will often be slower and more expensive in Coordinator Mode than in single-Agent mode because of orchestration overhead, including back-and-forth communication between Coordinator and Workers and repeated system prompts for each Worker. The ROI inflection point for Coordinator Mode appears on **complex tasks spanning multiple files and requiring parallel research or implementation**. In those cases, the time saved by parallelism outweighs the orchestration overhead. But the system prompt provides no cost-aware scheduling guidance, such as "for simple tasks, consider answering directly rather than launching Workers." Cost control depends entirely on the Coordinator's own judgment. ### Comparison with Other Multi-Agent Systems Compared with systems such as AutoGPT, CrewAI, and OpenAI Swarm, Claude Code's Coordinator Mode has several notable characteristics: - **No middleware layer**: there is no independent orchestration engine. The coordination logic exists entirely inside the LLM's system prompt. LangGraph uses Python state graphs, CrewAI uses DAG definitions, and Claude Code uses 370 lines of natural language - **Emphasis on synthesis**: most multi-Agent systems follow an "assign-and-aggregate" model, such as AutoGen's GroupChat, or a peer handoff model, such as OpenAI Swarm's handoff. Claude Code emphasizes "assign-understand-reassign" - **Enforced hierarchy**: unlike OpenAI Swarm's peer model, Claude Code strictly maintains the Coordinator-Worker hierarchy. Workers cannot delegate child Workers and cannot directly communicate with other Workers. This sacrifices flexibility but guarantees that the synthesis step cannot be skipped - **Anti-delegation rules**: explicitly forbidding lazy delegation is an uncommon but not entirely original design choice. CrewAI's hierarchical process also has a similar idea that the manager should understand before redistributing. Claude Code's uniqueness lies in enforcing this idea with detailed positive and negative examples - **Stoppable and resumable**: after a Worker is stopped, it can be continued with new instructions while retaining context, which is more efficient than destroying and recreating it - **The beginnings of persistent Agents**: the `subscribe_pr_activity` tool hints at an evolution from short-lived task execution toward long-running Agents. Cursor and Aider do not yet have an equivalent ### Overall Evaluation Coordinator Mode is a design that "uses simplicity to control complexity." A single 370-line file implements a complete multi-Agent orchestration framework through a carefully written system prompt. Its core architectural bet is **prompt-driven orchestration**: it bets that the model's instruction-following ability is strong enough to substitute for a code-level state machine and type system. Its central design choice is to establish "synthesis" as the Coordinator's primary responsibility rather than simple task dispatch. That is a meaningful differentiator in prompt-driven multi-Agent systems, although frameworks like CrewAI also have similar "manager Agent understands before redistributing" patterns. Claude Code's differentiation lies more in execution force, that is, 370 lines of detailed constraints, than in conceptual originality. The main risks are: (1) the reliability of prompt compliance, because system correctness depends on whether the model faithfully executes the constraints; (2) the linearly growing cost of parallel Workers, due to a lack of cost-aware scheduling; and (3) the unresolved tension between the persistent-Agent direction implied by `subscribe_pr_activity` and the existing "human in the loop" philosophy.