Multi-Agent Team

When a feature spans multiple layers — frontend, backend, database, infrastructure — a single Claude instance working sequentially can be slow. The multi-agent team build spawns multiple Claude instances that work in parallel, coordinating through a contract-first protocol to avoid integration conflicts.

When to use multi-agent builds

Use multi-agent builds when:

• The feature spans 2+ independent components (e.g., frontend and backend)
• Components have well-defined interfaces between them
• Parallel work would save significant time
• The feature is complex enough to justify the coordination overhead

Use the standard loop instead when:

• The task is focused on a single component or layer
• Changes are tightly coupled and hard to parallelize
• The task is a bug fix, refactor, or small feature
• You want lower cost (multi-agent builds run multiple Claude instances simultaneously)

Prerequisites

Before using /mx:build-with-agent-team, ensure:

1. Claude Code version

Agent Teams require Claude Code v2.1.32+. Check with:

claude --version

2. Experimental flag

Add to your Claude Code settings:

~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Without this flag, the command will stop with an error.

3. Display mode setup (optional)

Agent Teams support two display modes:

Mode	How it works	Requirements
In-process (default)	All teammates run in your main terminal. Use Shift+Down to cycle.	Any terminal
Split panes	Each teammate gets its own pane — full visibility of all output at once.	tmux or iTerm2

The default is "auto" — uses split panes if already inside tmux, in-process otherwise.

To install tmux (recommended for split panes):

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora
sudo dnf install tmux

To use iTerm2 split panes: install the it2 CLI, then enable the Python API in iTerm2 → Settings → General → Magic → Enable Python API.

To override the display mode, set teammateMode in ~/.claude.json:

~/.claude.json

{
  "teammateMode": "in-process"
}

Or pass per-session:

claude --teammate-mode in-process

Note

Split-pane mode is not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty. Use in-process mode in these environments.

Keyboard controls

Shortcut	Action
Shift+Down	Cycle through teammates (wraps back to lead after last)
Enter	View a teammate’s session (in-process mode)
Escape	Interrupt a teammate’s current turn
Ctrl+T	Toggle the shared task list

How it works

The multi-agent team build follows a structured protocol with phases.

Architecture

An agent team consists of:

Component	Role
Team lead	Your main Claude Code session — creates the team, spawns teammates, coordinates work
Teammates	Separate Claude Code instances that each work on assigned tasks
Task list	Shared list of work items that teammates claim and complete
Mailbox	Messaging system for direct communication between agents

Teams and tasks are stored locally:

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

Context and permissions

• Context: Teammates load CLAUDE.md, MCP servers, and skills automatically — but they do not inherit the lead’s conversation history. Include all task-specific context in the spawn prompt.
• Permissions: Teammates start with the lead’s permission settings. You can change individual teammate modes after spawning, but not at spawn time.

Phase 1: Contracts (sequential)

This is the most important phase. Agents building in parallel will diverge on interfaces unless they agree on contracts first.

1. Upstream agents spawn first (e.g., database agent, then backend agent)
2. Each upstream agent’s first task is to define and publish their contract — exact API endpoints, request/response shapes, status codes, error formats
3. The lead agent verifies each contract for:
   • Exact URLs, including trailing slashes
   • Explicit response shapes (not vague descriptions like “returns data”)
   • Error response formats
   • SSE event formats (if applicable)
4. The lead forwards verified contracts to downstream agents
5. Downstream agents spawn only after receiving their upstream contract

This staggered approach prevents the most common multi-agent failure: interface divergence.

Phase 2: Implementation (parallel)

After contracts are verified and distributed, all agents build in parallel. Each agent owns specific files and directories and must not touch other agents’ code. If an agent needs to deviate from the contract, it notifies the lead first.

Phase 3: Pre-completion contract diff

Before declaring completion, the lead runs a contract verification:

• “Backend: what exact curl commands test each endpoint?”
• “Frontend: what exact fetch URLs are you calling?”

The lead compares responses and flags any mismatches before integration. This catches contract drift that happened during implementation.

Phase 4: Cross-review

Each agent reviews another agent’s integration points. This catches issues at the boundaries between components — the most common source of integration bugs.

Communication patterns

Teammates can communicate using two patterns:

Pattern	When to use
message	Send to one specific teammate — e.g., “tell the backend agent to add a new endpoint”
broadcast	Send to ALL teammates simultaneously. Use sparingly — token costs scale with team size

In split-pane mode, click into any pane to interact with that teammate directly. In in-process mode, use Shift+Down to cycle to a teammate and type to send them a message.

Task management

The shared task list coordinates work across the team:

• Task states: pending → in progress → completed
• Dependencies: Tasks can depend on other tasks. A pending task with unresolved dependencies cannot be claimed until those dependencies are completed. When a dependency completes, blocked tasks unblock automatically.
• Assignment: The lead can assign tasks explicitly, or teammates can self-claim the next unassigned, unblocked task after finishing their current work.
• Race prevention: Task claiming uses file locking — no two teammates can claim the same task simultaneously.

Task sizing

Aim for 5–6 tasks per teammate. Too small and coordination overhead exceeds the benefit. Too large and teammates work too long without check-ins. The right size is a self-contained unit with a clear deliverable — a function, a test file, or a review.

Plan approval mode

For complex or risky components, require teammates to plan before implementing:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either:

• Approves — the teammate exits plan mode and begins implementation
• Rejects with feedback — the teammate stays in plan mode, revises, and resubmits

Influencing the lead’s judgment: Give it criteria in your prompt — e.g., “only approve plans that include test coverage” or “reject plans that modify the database schema.”

Quality gates with hooks

Use hooks to enforce rules automatically when teammates finish work or tasks change state:

Hook	Fires when	Use for
TeammateIdle	A teammate is about to go idle	Exit code 2 → sends feedback and keeps the teammate working
TaskCreated	A task is being created	Exit code 2 → prevents creation with feedback
TaskCompleted	A task is being marked complete	Exit code 2 → prevents completion with feedback (e.g., “run tests first”)

Configure these in your project’s hooks config. Examples:

• “All tasks must have passing tests before completion” — use TaskCompleted to verify
• “No teammate goes idle without reporting status” — use TeammateIdle to enforce
• “Tasks must include acceptance criteria” — use TaskCreated to validate

QA agent protocol

Every team build includes a dedicated QA teammate that verifies completed work before tasks can close. The QA agent uses the mx-quality-keeper persona and never writes production code. It does not count toward the implementation team size — if you specify 3 agents, the team will be 3 builders + 1 QA.

How it works

1. Implementation agents complete tasks using a test-first cycle: write the test → confirm it fails → implement the feature → confirm it passes
2. When a task is marked complete, the QA agent verifies it:
   • Runs lint, type-check, and tests on changed files
   • Checks for new type/lint suppressions
   • Verifies contract conformance (do implementations match the agreed interfaces?)
3. If verification passes, the task stays completed and dependent tasks unblock
4. If verification fails, the QA agent messages the owning agent with specific failure details and the task reverts to in-progress

The rejection loop

The QA agent enforces a structured retry protocol:

Attempt	QA action
1st failure	Messages owning agent with failure details and required fix
2nd failure	Messages with additional context about why the previous fix did not resolve the issue
3rd failure	Escalates to the lead with a summary of all attempts

After 3 failed attempts, the lead decides how to proceed — reassign the task, pair with the agent, or descope.

QA verification scope

The QA agent checks:

Check	What it verifies
Quality commands	Lint, type-check, tests pass on changed files
Suppressions	No new @ts-ignore, eslint-disable, etc. without justification
Contract conformance	Implementation matches the agreed API contract (endpoints, shapes, status codes)
Spec conformance	Every must-have from the PRD was actually built, wired up, and works as specified — verified per user role (Admin, Customer, etc.). Reports PASS/FAIL/MISS per role and requirement ID.
Test coverage	Every implemented feature has a corresponding test written test-first (e2e for user flows, unit for business logic). If an agent skipped the test-first cycle, QA fails the task.
Integration points	Cross-boundary calls match (frontend URLs match backend endpoints)

Hook configuration for QA

Use the TaskCompleted hook to enforce QA verification before tasks can close:

.claude/settings.json

{
  "hooks": {
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Task completion requires QA verification. Message the QA agent to verify this task before marking complete.' && exit 2"
          }
        ]
      }
    ]
  }
}

This blocks task completion with a feedback message, prompting the teammate to request QA verification first. The QA agent then runs its checks and either confirms the completion or routes a failure.

QA agent is role-agnostic

The QA agent works with any team composition. It does not need to understand the domain — it runs the project’s existing quality commands and verifies contracts. A frontend/backend team, a microservices team, or a DevOps/infra team all get the same verification protocol.

Running a multi-agent build

Step 1: Create a PRD

/mx:prd "real-time collaboration feature with presence indicators"

The PRD defines the feature’s requirements, scope, and acceptance criteria. This gives the agent team a clear specification to build from.

Step 2: Create a plan

Either run /mx:plan to generate a plan from the PRD, or write a plan document manually. The plan should include:

• What components are needed
• How they interact
• What the dependencies are between components

Step 3: Launch the team

/mx:build-with-agent-team <path-to-plan> [num-agents]

The command reads the plan and determines the team structure:

Team size	When to use
2 agents	Clear frontend/backend split
3 agents	Full-stack (frontend, backend, database/infra)
4 agents	Additional concerns (testing, DevOps)
5+ agents	Large systems with many independent modules

You can specify the team size explicitly, or let the command decide based on the plan. You can also specify a model per teammate (e.g., “Use Sonnet for each teammate”).

The command automatically spawns a QA teammate in addition to the implementation agents. You do not need to account for the QA agent in your team size number.

Sizing guidance: Start with 3–5 teammates. Token costs scale linearly with team size, so only scale up when the work genuinely benefits from parallelism. Three focused teammates often outperform five scattered ones.

Step 4: Enter Delegate Mode

After spawning agents, the lead enters Delegate Mode. The lead should not implement code — only coordinate:

• Verify and forward contracts
• Resolve conflicts between agents
• Answer questions from agents
• Run end-to-end validation after all agents complete

Use Shift+Down to cycle through teammates. In split-pane mode, click into a pane to interact directly.

Lead not waiting

Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this, tell it: “Wait for your teammates to complete their tasks before proceeding.”

Step 5: Lead validation (end-to-end)

After all agents report done and the QA agent confirms all tasks have passed verification, the lead runs end-to-end validation:

1. QA summary clean? — Review the QA agent’s final report — any unresolved failures or escalations?
2. Can the system start? — Start all services, check for startup errors
3. Does the happy path work? — Walk through the primary user flow
4. Do integrations connect? — Verify data flows from frontend through backend to database
5. Are edge cases handled? — Empty states, error states, loading states

If validation fails, the lead identifies which agent’s domain contains the bug, re-spawns that agent with the specific issue, and re-runs validation after the fix.

Step 6: Shutdown and cleanup

Graceful shutdown:

1. Ask each teammate to shut down: “Ask the [role] teammate to shut down”
2. The teammate can approve (exits gracefully) or reject with an explanation
3. Teammates finish their current request/tool call before stopping — this can take time

Team cleanup — after all teammates have shut down:

Clean up the team

Cleanup rules

• Always use the lead to clean up — never a teammate (their team context may not resolve correctly)
• Cleanup will fail if any teammates are still running — shut them all down first
• The lead can only manage one team at a time — clean up before starting a new team

The spawn prompt

Each agent receives a prompt that defines their role, ownership, and constraints:

You are the [ROLE] agent for this build.

## Your Ownership
- You own: [directories/files]
- Do NOT touch: [other agents' files]

## What You're Building
[Relevant section from plan]

## Before You Build (REQUIRED)
- Your FIRST deliverable is your [API contract / schema / interface]
- Send it to the lead via message BEFORE writing implementation code
- Wait for lead to confirm before proceeding

## The Contract You Must Conform To
[Upstream agent's verified contract]

## Cross-Cutting Concerns You Own
[Integration behaviors this agent is responsible for]

## Project Conventions
- Run quality checks after changes (see CLAUDE.md)
- Commit format: <type>(<scope>)[TICKET] <description>

## Before Reporting Done
Run these validations and fix any failures:
1. [specific validation command]
2. [specific validation command]
Do NOT report done until all validations pass.

Common pitfalls

Pitfall	Problem	Prevention
Fully parallel spawn	All agents start at once, interfaces diverge	Stagger spawns: upstream first, contracts verified before downstream
Lead over-implementing	Lead starts writing code instead of coordinating	Stay in Delegate Mode — coordinate only
Implicit contracts	”Returns sessions” — what does that mean?	Require exact JSON shapes, URLs, and status codes
File conflicts	Two agents edit the same file	Assign clear, non-overlapping file ownership
Orphaned cross-cutting concerns	Streaming, URL conventions, error shapes have no owner	Explicitly assign ownership of every cross-cutting concern
Lead not waiting	Lead starts implementing instead of delegating	Tell it “Wait for your teammates to complete their tasks”
Task status lag	Teammates fail to mark tasks complete, blocking dependents	Check if work is done and update manually or nudge the teammate

Troubleshooting

Problem	Solution
Teammates not appearing	In in-process mode, press Shift+Down — they may be running but not visible. For split panes, verify which tmux or that iTerm2’s it2 CLI is installed. Check that the task is complex enough to warrant a team.
Too many permission prompts	Pre-approve common operations in your permission settings before spawning teammates.
Teammates stopping on errors	Check their output via Shift+Down or click their pane. Give additional instructions directly, or spawn a replacement.
Lead shuts down early	Tell the lead to keep going and wait for teammates to finish.
Orphaned tmux sessions	Run tmux ls then tmux kill-session -t <session-name> to clean up.
/resume or /rewind after crash	These do NOT restore in-process teammates. Tell the lead to spawn new teammates.

Limitations

Current known limitations of agent teams:

• No session resumption: /resume and /rewind do not restore in-process teammates
• One team per session: Clean up the current team before starting a new one
• No nested teams: Teammates cannot spawn their own teams — only the lead can
• Lead is fixed: Cannot promote a teammate to lead or transfer leadership
• Permissions set at spawn: All teammates inherit lead’s mode; change individually after spawning
• Split panes restricted: Not supported in VS Code terminal, Windows Terminal, or Ghostty
• Task status can lag: Teammates sometimes fail to mark tasks completed, blocking dependents
• Shutdown can be slow: Teammates finish their current request before stopping

Agent Teams vs Sub-Agents

mx-workflow uses two forms of multi-agent execution. Here is when to use each:

	Sub-Agents (Task tool)	Agent Teams
Context	Own context window; results return to caller	Own context window; fully independent
Communication	Reports to main agent only	Teammates message each other directly
Coordination	Main agent manages all	Shared task list, self-coordination
Visibility	Results summarized	Each visible in own pane or via Shift+Down
Best for	Focused tasks where only the result matters	Complex work requiring discussion and collaboration
Cost	Lower (results summarized back)	Higher (separate Claude instances)

Use Sub-Agents when work is isolated and agents do not need to coordinate with each other — for example, running code review and test analysis in parallel during /mx:implement.

Use Agent Teams when components depend on each other and agents need to share contracts, resolve conflicts, and verify integration points.