Agent Clusters - When AI Starts 'Forming Squads'

Have you ever encountered this: you ask Claude Code to handle a complex task, but the context is almost full and it’s only half done?

What you need is “forming a squad” - letting multiple AI Agents work together. Today let’s talk about Claude Code’s Agent clusters and see how AI “forms parties to tackle bosses.”

Why Multi-Agent? Division of Labor is More Efficient

Imagine you’re renovating a house:

• Single Agent mode: One worker has to design, build, and inspect - exhausted and still can’t finish
• Multi-Agent mode: Designer draws blueprints, construction team builds, supervisor inspects - everyone does their own job

AI Agents work the same way. When tasks get complex:

• A single Agent has limited context
• Some tasks can run in parallel (searching, analyzing, coding)
• Verification needs “a second pair of eyes”

Claude Code provides three multi-Agent modes, from light to heavy: standard sub-Agent, Fork mode, and Coordinator mode.

Mode 1: Standard Sub-Agent - Independent Small Tasks

This is the most basic mode. The main AI (parent Agent) spawns a sub-Agent to do independent work.

Parent Agent: Help me investigate this bug
    ↓
Spawn sub-Agent (type: explore)
    ↓
Sub-Agent searches codebase, returns results
    ↓
Parent Agent continues processing

Key characteristics:

• Sub-Agent starts from scratch, only sees the prompt passed by parent Agent
• Own system prompt, own context
• Can run foreground or background
• Allows recursion (sub-Agent can spawn its own sub-Agents)

Use cases:

• Independent investigation tasks
• Parallel work that doesn’t interfere with main conversation
• Specialized capabilities from specific Agent types

Built-in Agent types include:

• general-purpose: general tasks
• verification: verify implementation (read-only, no editing)
• Explore: code exploration
• Plan: planning tasks

Mode 2: Fork Mode - Parallel with Inherited Context

Fork mode is an experimental feature with a key difference: the sub-process inherits the parent Agent’s complete conversation context.

This is like:

• Standard sub-Agent: new employee joins, starts from scratch learning the project
• Fork mode: clone a complete set of project materials for the new colleague

How Fork works:

Parent Agent's complete conversation history
    ↓
Fork subprocess inherits all messages
    ↓
Append one instruction: "Please handle this part"
    ↓
Execute in parallel, shared cache

Key characteristics:

• Inherits parent Agent’s model and system prompt (ensures cache hits)
• Forced background execution
• Recursive Fork prohibited (prevents infinite spawning)
• Shares parent Agent’s prompt cache

Why prohibit recursive Fork?

Fork subprocess inherits the Agent tool - if it could Fork, it could theoretically spawn infinitely. Code has two layers of protection:

1. Check querySource (anti-compression)
2. Scan for <fork-boilerplate> tags in messages (backup check)

This is like: company policy - a department can only be split once, no further subdivisions.

Mode 3: Coordinator Mode - General Contractor for Complex Projects

Coordinator mode is the heavyweight multi-Agent solution. The main Agent becomes a “Coordinator that doesn’t code directly” - it only assigns tasks to Workers.

Four-phase workflow:

1. Research: Workers investigate codebase in parallel
2. Synthesis: Coordinator understands the problem, writes implementation specification
3. Implementation: Workers modify code according to spec
4. Verification: Workers verify changes are correct

Core principle: Never delegate understanding

Coordinator prompts explicitly require:

• No writing “based on your findings”
• Coordinator must understand the problem itself
• Workers only execute, don’t think

This is like:

• Architect must understand requirements themselves, can’t just relay to construction team
• Project manager needs to know the business, can’t just be a messenger

Coordinator’s toolset:

• Agent: spawn Workers
• SendMessage: send follow-up instructions to Workers
• TaskStop: stop Workers
• No editing tools (can’t code directly)

Agent Swarm: Flat Team Structure

The teammate system (Agent Swarm) creates a flat-structured team that collaborates through message passing.

TeamCreateTool: create new team

{
  "team_name": "my-team",
  "description": "Frontend development team",
  "agent_type": "frontend-dev"
}

TeammateAgentContext: teammate’s identity

• agentId: full ID (e.g., researcher@my-team)
• teamName: team affiliation
• planModeRequired: whether plan approval is needed
• isTeamLead: whether it’s the Leader

Flat structure constraints:

• Teammates cannot spawn other teammates (team roster is flat)
• In-process teammates cannot spawn background Agents

This is like: a basketball team has 5 starters, no “substitute of a substitute.”

Verification Agent: Quality Control’s “Second Pair of Eyes”

Verification Agent is the most refined Agent type, dedicated to verifying implementation correctness.

Design principles:

1. Read-only constraint: cannot modify project, can only write temp scripts to /tmp
2. Strict verdicts: output must end with VERDICT: PASS/FAIL/PARTIAL
3. Adversarial probing: must run concurrency, boundary value, and idempotency tests

Failure mode checklist:

• Verification avoidance: finding excuses not to execute verification, just looking at code and writing “PASS”
• Seduction by the first 80%: seeing pretty UI and passing, missing that half the buttons don’t work

This is like: quality inspector can’t pass a product just because the packaging looks good - must actually test functionality.

Inter-Agent Communication: Message Routing

SendMessageTool: core of inter-Agent communication

Addressing modes:

• to: "tester": send to specific teammate
• to: "*": broadcast to all teammates
• to: "uds:/path/to/socket": UDS mode to other Claude Code instances
• to: "bridge:<session-id>": Remote Control mode

Message types:

• Plain text messages
• Close request/response
• Plan approval response

Mailbox system: File-system-based mailbox design - cross-process teammates can communicate through shared filesystem. Each message contains sender, content, summary, timestamp, color.

Worker result callback: After Worker completes task, injects into Coordinator’s conversation using <task-notification> XML format:

<task-notification>
  <task-id>worker-123</task-id>
  <status>completed</status>
  <summary>Task completion summary</summary>
  <result>Detailed results</result>
  <usage>
    <total_tokens>1500</total_tokens>
  </usage>
</task-notification>

Async Agent Lifecycle

When an Agent goes to background (run_in_background, Fork mode, Coordinator mode, etc.), the lifecycle is:

1. Register: registerAsyncAgent() creates record, allocates agentId
2. Execute: runs under runWithAgentContext()
3. Progress reporting: updates status via updateAsyncAgentProgress()
4. Complete/Fail: calls completeAsyncAgent() or failAsyncAgent()
5. Notify: enqueueAgentNotification() injects results into parent Agent message stream

Key design: background Agent is not tied to parent Agent’s abortController. When user presses ESC to cancel main thread, background Agents continue running - can only be explicitly terminated via chat:killAgents.

This is like: boss leaves the meeting, employees keep working, unless boss specifically says “stop.”

Worktree Isolation: Protecting Main Branch

When Agent uses isolation: 'worktree':

• Runs in temporary git worktree
• All modifications in isolated environment
• Worktrees without changes auto-cleanup
• Worktrees with changes preserve branches, path returned to caller

This is like: renovating in a model apartment, doesn’t affect actual residents.

Comparison of Three Modes

Practical: How to Choose a Mode

Scenario 1: Search for API calls in codebase

Use standard sub-Agent, type Explore.

• Independent task, doesn’t need inherited context
• Explore type Agent is specialized for this

Scenario 2: Analyze multiple files simultaneously

Use Fork mode.

• Needs parent Agent’s context understanding
• Process multiple files in parallel
• Shared cache, cost savings

Scenario 3: Refactor entire authentication module

Use Coordinator mode.

• Complex multi-step task
• Needs research, design, implementation, verification division
• Coordinator maintains global view

Scenario 4: Verify bug fix

Use Verification Agent.

• Read-only verification, doesn’t affect code
• Adversarial probing ensures quality
• VERDICT gives clear results

Implications for Building AI Agents

Pattern 1: Context Sharing vs Execution Isolation Tradeoff

No one-size-fits-all solution:

• Want isolation → standard sub-Agent
• Want sharing → Fork mode
• Want global view → Coordinator mode

Pattern 2: Flat Team Structure

Prohibiting nested teammates reflects organizational principle: coordination should集中在一个节点，避免过深的委托链。

Pattern 3: Anti-Pattern Checklist

Verification Agent prompts list typical failure modes, requiring model to “recognize its own rationalization excuses.” This is engineering compensation for LLM inherent weaknesses.

Summary

Agent clusters are Claude Code’s core capability for handling complex tasks:

• Three modes: standard sub-Agent, Fork mode, Coordinator mode
• Agent Swarm: flat team structure, message-passing collaboration
• Verification Agent: read-only verification, adversarial probing
• Worktree isolation: protecting main branch
• Lifecycle management: register → execute → report → complete → notify

This is like:

• Standard sub-Agent: outsourcing independent tasks
• Fork mode: clone team for parallel assault
• Coordinator mode: general contractor + special forces collaboration
• Verification Agent: quality control department

Understanding Agent clusters lets you:

• Reasonably split complex tasks
• Choose appropriate collaboration mode
• Implement multi-Agent architecture in your own AI Agents

Next up: Effort, Fast Mode, and Thinking - AI’s “Thinking Depth” Control Knob.