Multi-Agent Co-work

Multi-agent co-work is an approach where multiple Claude instances each take a role and collaborate. Instead of one agent handling everything, specialized agents work in parallel and their results are integrated.

Co-work vs. a Single Agent

Aspect	Single agent	Multi-agent co-work
Processing	Sequential	Parallel
Context	One long context	Independent contexts each
Specialization	General-purpose	Specialized by role
Speed	Slow	Fast
Cost	Low	High (scales with parallelism)
Good fit	Simple tasks	Complex, large-scale tasks

Basic Co-work Patterns

Role-division architecture

[User request]
      ↓
[Coordinator agent] — analyzes the work and assigns roles
      ↓
┌─────────────────────────────────────────────┐
│  [Researcher]    [Developer]    [Reviewer]   │
│  (gathers info)  (writes code)  (checks QA)  │
└─────────────────────────────────────────────┘
      ↓
[Coordinator agent] — integrates results and produces the final response

Requesting co-work in Claude Code

> I need to add a new feature to our payment system.
  Split it into three roles and proceed:

  1. Researcher: analyze the current payment/ code and
     figure out the architecture and patterns
  2. Developer: implement the refund feature
     based on the researcher's findings
  3. Reviewer: review the developer's code and
     find security issues and edge cases

Implementing Co-work with the Agent SDK

Expert-panel pattern

Multiple expert agents each analyze the same problem:

import { query } from "@anthropic-ai/claude-agent-sdk";

interface ExpertOpinion {
  role: string;
  analysis: string;
  recommendation: string;
}

async function expertPanel(problem: string): Promise<string> {
  const experts = [
    {
      role: "Security Expert",
      prompt: `As a security expert, analyze the following problem.
        Focus on security vulnerabilities and risk factors:
        ${problem}`
    },
    {
      role: "Performance Expert",
      prompt: `As a performance optimization expert, analyze the following problem.
        Focus on bottlenecks and scalability issues:
        ${problem}`
    },
    {
      role: "UX Expert",
      prompt: `As a UX designer, analyze the following problem.
        Focus on user experience and accessibility:
        ${problem}`
    }
  ];

  // All experts analyze simultaneously
  const opinions = await Promise.all(
    experts.map(async (expert) => {
      const response = await query({
        prompt: expert.prompt,
        options: { maxTurns: 8 }
      });
      return {
        role: expert.role,
        analysis: extractText(response)
      } as ExpertOpinion;
    })
  );

  // The coordinator synthesizes the opinions
  const synthesis = await query({
    prompt: `Synthesize the opinions of these three experts into
    a balanced final recommendation:

    ${opinions.map(o => `### ${o.role}\n${o.analysis}`).join("\n\n")}

    For conflicting opinions, explain the trade-offs and
    present them along with priorities.`,
    options: { maxTurns: 5 }
  });

  return extractText(synthesis);
}

Pipeline co-work pattern

Each agent picks up and improves on the previous agent's work:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function writingPipeline(topic: string): Promise<string> {
  // Step 1: the researcher gathers material
  console.log("📚 Researcher: gathering material...");
  const research = await query({
    prompt: `Research ${topic}.
      Organize the key concepts, latest trends, and major data
      in a structured way.`,
    options: {
      maxTurns: 10,
      allowedTools: ["WebSearch", "Read"]
    }
  });
  const researchResult = extractText(research);

  // Step 2: the writer drafts
  console.log("✍️ Writer: drafting...");
  const draft = await query({
    prompt: `Based on the following research material,
    write a draft blog post.
    Audience: developers / Tone: friendly but professional

    Research material:
    ${researchResult}`,
    options: { maxTurns: 8 }
  });
  const draftResult = extractText(draft);

  // Step 3: the editor polishes
  console.log("📝 Editor: proofreading and improving...");
  const edited = await query({
    prompt: `Edit the following blog draft:
    - Improve unclear sentences
    - Check the logical flow
    - Optimize keywords for SEO
    - Add a CTA that increases reader engagement

    Draft:
    ${draftResult}`,
    options: { maxTurns: 6 }
  });

  return extractText(edited);
}

Role-Specialized System Prompts

Give each agent a clear persona:

const agentConfigs = {
  architect: {
    systemPrompt: `You are a senior software architect.
      You always prioritize scalability, maintainability, and pattern consistency.
      Focus on design decisions rather than writing code.`,
    maxTurns: 5
  },
  developer: {
    systemPrompt: `You are a full-stack developer.
      You write the actual implementation code according to architecture decisions.
      Write testable, readable code.`,
    maxTurns: 20,
    allowedTools: ["Read", "Edit", "Write", "Bash"]
  },
  tester: {
    systemPrompt: `You are a QA engineer.
      Your goal is to find edge cases, exceptional situations, and security vulnerabilities.
      Focus on the parts the developer missed.`,
    maxTurns: 10,
    allowedTools: ["Read", "Glob", "Grep"]
  }
};

async function developFeature(requirement: string) {
  // 1. The architect designs
  const designResponse = await query({
    prompt: requirement,
    options: agentConfigs.architect
  });
  const design = extractText(designResponse);

  // 2. The developer implements
  const implementResponse = await query({
    prompt: `Implement the following architecture design:\n${design}`,
    options: agentConfigs.developer
  });
  const implementation = extractText(implementResponse);

  // 3. QA reviews
  const reviewResponse = await query({
    prompt: `Review the following implementation code:\n${implementation}`,
    options: agentConfigs.tester
  });

  return {
    design,
    implementation,
    review: extractText(reviewResponse)
  };
}

Conflict Resolution Pattern

How to handle disagreements between agents:

async function resolveConflict(
  agentA: string,
  agentB: string,
  opinions: [string, string]
): Promise<string> {
  const mediator = await query({
    prompt: `Two experts disagree.
    Analyze objectively and reach the best conclusion.

    ${agentA}'s opinion:
    ${opinions[0]}

    ${agentB}'s opinion:
    ${opinions[1]}

    Conclusion format:
    1. Valid points of each opinion
    2. The core point of conflict
    3. Recommended resolution and why`,
    options: { maxTurns: 4 }
  });

  return extractText(mediator);
}

Cross-Session Messaging

Claude Code (v2.1.224+) can send and receive messages with other Claude Code sessions running on the same machine.

When a session modifies existing code or makes an important discovery, it can inform other sessions working on related code. You do not need to manually copy and paste between terminals; Claude uses the ListAgents and SendMessage tools to autonomously discover other sessions and deliver messages.

How to use

• Autonomous decision: When Claude determines that another session needs to know something during parallel work, it will proactively send a message.
• Explicit instruction: You can prompt Claude directly, e.g., "Tell the session running in the other terminal that the migration is complete."
• @ Mention (v2.1.232+): Typing @ in the prompt window auto-completes the names of other currently running sessions. Example: @api-worker tell them the schema migration is done.

Using the /list-agents (or /peers) command, you can view the list of sessions currently available to receive messages (subagents, local sessions, background sessions, and cloud/other machine sessions connected via Remote Control).

Controlling Inbound Messages

You can control whether to receive messages from other sessions via the crossSessionInbound setting or Messages from your other sessions in the /config menu.

• accept: Receives immediately and passes it to Claude.
• hold: Only shows a notification and holds it (you decide with Approve/Deny buttons in the chat window).
• refuse: Silently blocks the message.

Security Model

Messages sent from other sessions do not have the same permissions as your explicit prompts. Commands arriving via message (e.g., /compact) are not executed but treated as plain text, strictly following the receiving session's permission mode settings (such as auto-mode) and approval principles.

Limitations & Constraints

• Plain Text Only: Inter-session messaging is strictly text-based. File contexts or entire conversation histories are not duplicated across sessions. If full context is needed, use the /resume command to take over that session directly instead of messaging.
• OS Support: Works perfectly on macOS, Linux, and WSL2 environments on Windows. However, native Windows environments (CMD, PowerShell) are not currently supported.

Agent Teams (Built-in Feature)

Beyond the Agent SDK-based implementations above, Claude Code has a built-in Agent Teams feature. You can request multi-agent collaboration in natural language without writing any code.

Experimental feature

Agent Teams is currently an experimental feature. There are known limitations with session resume, task coordination, and shutdown behavior.

Subagents vs. Agent Teams

Aspect	Subagents	Agent Teams
Context	Only results returned to main	Fully independent
Communication	Reports only to the main agent	Direct messages between teammates
Coordination	Managed by the main agent	Shared task list + autonomous selection
Good fit	Focused tasks where only the result matters	Complex work requiring discussion and collaboration
Token cost	Low (only results summarized)	High (each teammate is an independent instance)

Enabling

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Team architecture

Component	Role
Team leader	The main Claude Code session. Creates teammates, assigns work, coordinates results
Teammate	A separate Claude Code instance. Performs assigned work independently
Task list	A shared task list. Teammates pull work autonomously
Mailbox	A direct messaging system between teammates (message + broadcast)

Teams and tasks are stored locally:

• Team config: ~/.claude/teams/{team-name}/config.json
• Tasks: ~/.claude/tasks/{team-name}/

Best-fit scenarios

• Research and review: multiple teammates investigate simultaneously from different angles
• New module/feature: each teammate owns a different part
• Competing-hypothesis debugging: verify multiple theories in parallel and converge
• Cross-layer work: front-end, back-end, and tests each owned separately

Usage example

> I need to design a CLI tool. Create an Agent Team to explore it from different angles:
  - 1 person for UX
  - 1 person for technical architecture
  - 1 critic to push back

Claude creates the team, spawns the teammates, and coordinates the work through the shared task list.

Display modes

Mode	Description	Requirements
in-process	Switch with Shift+Down in a single terminal	None (default)
split-panes	Each teammate in a separate pane	tmux or iTerm2
auto	Split in a tmux session, otherwise in-process	-

// settings.json
{ "teammateMode": "in-process" }

# Per-session override
claude --teammate-mode in-process

Split pane limitations

Split-pane mode is not supported in the VS Code integrated terminal, Windows Terminal, or Ghostty. tmux or iTerm2 is required.

Communicating directly with teammates

Each teammate is a fully independent Claude Code session:

In-process mode:

• Shift+Down: switch between teammates
• Enter: enter a teammate session → Esc to interrupt
• Ctrl+T: toggle the task list

Split-pane mode:

• Click a pane to interact directly

Task management

Tasks are managed in three states: pending → in progress → completed. Dependencies between tasks are also supported.

• Leader assigns: designate a task to a specific teammate
• Autonomous selection: after finishing, a teammate automatically picks the next unassigned, unblocked task
• File locking: prevents multiple teammates from selecting the same task at once

Plan approval

For complex or risky work, you can require teammates to get plan approval before implementing:

Create an architect teammate to refactor the auth module.
Have them get plan approval before making changes.

When the teammate finishes the plan, they request approval from the leader. On rejection, they re-plan with the feedback.

Team cleanup

> Clean up the team

Clean up through the leader. If teammates are still running, they must be shut down first. If teammates clean up directly, resources can end up in an inconsistent state.

Quality-gate hooks

{
  "hooks": {
    "TaskCompleted": [{
      "hooks": [{
        "type": "command",
        "command": "npm test -- --related $CHANGED_FILES"
      }]
    }],
    "TeammateIdle": [{
      "hooks": [{
        "type": "command",
        "command": "./scripts/check-remaining-work.sh"
      }]
    }]
  }
}

Returning exit code 2 delivers feedback to the teammate, and they continue working.

Best Practices

Token Cost Explosion Warning (Real-World Case)

Each teammate is a fully independent Claude instance. Five teammates consume 5x the tokens, and in debate or parallel exploration patterns where teammates frequently message each other, API costs can easily exceed $80 within 15 minutes.

• Cost Optimization Rules:
  1. Use Subagents for straightforward summary tasks; only enable Agent Teams when active discussion or autonomous division of labor is strictly required.
  2. Set teammate models to Sonnet or Haiku instead of Opus to defend against runaway costs.
  3. Always cleanly tear down idle teammates immediately when finished with > clean up the team.

• Start with 3–5 teammates (best cost-to-benefit)
• Assigning 5–6 tasks per teammate is about right
• Separate file ownership between teammates (avoid simultaneous edits to the same file)
• Combining with Worktree prevents file conflicts entirely
• Give teammates sufficient context (conversation history is not inherited)
• Using Sonnet as the teammate model is recommended (balance of capability and cost)
• Check progress periodically and correct course

Limitations

• /resume and /rewind do not restore in-process teammates
• Task states can lag, so manual updates are sometimes needed
• Only one team can be managed per session
• No nested teams (teammates cannot create their own teams)
• All teammates start with the leader's permission mode (can be changed individually after spawning)

Co-work Design Principles

Effective co-work design

1. Clarify roles: define each agent's scope of responsibility so they don't overlap
2. Unify interfaces: standardize the data-exchange format between agents
3. Guarantee independence: design so that one agent's failure doesn't stop the whole system
4. Summarize context: compress hand-offs between agents down to the essentials

Common mistakes

• Subagent results fill the main context: if several subagents return detailed results, they consume the main conversation's context quickly. If you need continuous parallel work, consider Agent Teams instead of subagents
• Ambiguous role boundaries lead to duplicated work
• Sequential dependencies without failure handling → one agent's failure halts everything