Multi-Agent Orchestration

Core Thesis

The bottleneck is no longer the model — it's you.

"The true constraint of agentic engineering now is twofold. It's the tools we have available and it's you and I — our ability to prompt engineer and context engineer the outcomes we're looking for."

Andy Devdan

Architecture

The Three Pillars

⚡

Spin up specialized agent teams via Claude Code's experimental CLAUDE_CODE_AGENT_TEAMS=1 flag. A primary orchestrator creates task lists, spawns sub-agents (each with own context window, model, session), they work in parallel, report back, then get deleted. Specialized agents doing one thing extraordinarily well.

👁

Multi-Agent Observability

You can't improve what you can't see. A custom observability dashboard captures session start/end events, tool calls per agent, swim lanes, and real-time status. Runs inside T-Mux for pane-based visualization of each sub-agent. Know exactly what every agent is doing at all times.

🧊

Agent Sandboxes

Secure isolated environments (E2B) where agents do work without jeopardizing your local machine. Andy had 24 running simultaneously. Pattern: rapid prototype in sandbox → if you like it, copy locally. Sandboxes live for 12 hours. Also works with local hardware (Mac Mini) for privacy-sensitive workflows.

Lifecycle

Agent Team Workflow

Create Team

team_create

Create Tasks

task_create × N

Spawn Agents

One per task

Parallel Work

Independent contexts

Send Messages

Report results

Delete Team

Reset context

Tooling

New Claude Code Agent Tools

Team Management

team_createInitialize a new agent team

team_deleteShutdown & cleanup team

TaskKick off agent in parallel (pre-existing)

Task Management

task_createDefine work unit for sub-agent

task_listView all active tasks

task_getCheck individual task status

task_updateModify task parameters

Communications

send_messageInter-agent messaging — the most critical tool

Insights

Key Takeaways

Context Window Efficiency

8 sub-agents explored 8 full-stack codebases and the primary orchestrator only used 31% of its context window — sub-agents do the heavy lifting in their own context.

Delete Teams When Done

Deleting agents after completion forces good context engineering patterns — you reset context and start fresh. This prevents context rot.

T-Mux for Visualization

Running Claude Code inside T-Mux gives you visual panes for each sub-agent. You see the orchestrator and all workers simultaneously.

Information-Dense Keywords

"Build a new agent team" — these are trigger phrases that tell the orchestrator to use specific multi-agent tools. Prompt engineering matters.

Ad Hoc Teams for Iteration

Don't just run one team — fire off ad hoc agent teams for specific follow-up work, bug fixes, and refinements iteratively.

Core Four Framework

Everything boils down to: Context + Model + Prompt + Tools. Every new feature is just a new combination of these four.

Prompts

Copy-Paste Prompt Templates

Multi-Agent Orchestration — Environment Setup

# Multi-Agent Orchestration Setup
# Run these commands in sequence to enable agent teams in Claude Code

# Step 1: Start T-Mux session (required for pane visualization)
tmux

# Step 2: Enable experimental agent teams feature
export CLAUDE_CODE_AGENT_TEAMS=1

# Step 3: Launch Claude Code inside T-Mux
claude

# You are now running Claude Code in team mode.
# The orchestrator agent can now:
#   - Create agent teams (team_create)
#   - Assign tasks to sub-agents (task_create)
#   - Spawn parallel agents in new T-Mux panes
#   - Receive results via send_message
#   - Clean up when done (team_delete)
#
# IMPORTANT: Each sub-agent gets its own:
#   - Context window (independent, no sharing)
#   - Model instance
#   - Session ID
#   - T-Mux pane (visual feedback)

Codebase Analysis Agent Team

# Prompt to send to your primary orchestrator agent in Claude Code
# This spawns a team of specialized agents to analyze multiple codebases

Build a new agent team for each codebase in this directory.

Have each agent:
1. Explore and understand the full codebase structure
2. Identify the tech stack (frontend, backend, database, dependencies)
3. Document how to set it up and run it locally
4. Summarize the application's purpose and key features
5. List any environment variables or configuration needed
6. Report back with a structured summary

Each agent should focus on ONE codebase only. Work in parallel.
When all agents complete, compile a master summary of all codebases.

# WHY THIS WORKS:
# - "Build a new agent team" triggers team_create
# - "for each codebase" triggers one task_create per directory
# - "Work in parallel" triggers concurrent agent spawning
# - "report back" triggers send_message to orchestrator
# - "compile a master summary" keeps orchestrator context clean (31% usage)

Sandbox Reboot Agent Team

# Prompt for spawning agents to rehost applications in fresh sandboxes
# Customize the skill references to match your setup

Build a new agent team using agent sandboxes.

Use the /reboot skill to mount the following directories in their own agent sandbox:
- [directory_1]
- [directory_2]
- [directory_3]
- [directory_4]

Be sure to set up every agent with:
1. Run the agent sandbox skill to understand the environment
2. Run the /reboot command skill to understand the deployment process
3. Create a fresh E2B sandbox instance
4. Upload the application codebase
5. Install all dependencies
6. Start the application
7. Verify it's running and report the live URL back

Each agent handles ONE application. All agents work in parallel.
When complete, provide all live URLs in a consolidated summary.

# PATTERN: Rapid prototype in sandbox → verify → copy locally if good
# Each sandbox lives for 12 hours
# You can run 20+ sandboxes simultaneously

CLAUDE.md — Multi-Agent Orchestration System Prompt

# Add this to your CLAUDE.md or project-level instructions
# This primes the orchestrator agent for multi-agent workflows

# Multi-Agent Orchestration Protocol

## Core Principle
Scale compute to scale impact. Use specialized agent teams where each 
agent does ONE thing extraordinarily well, then shuts down.

## Agent Team Lifecycle
1. CREATE TEAM → Initialize with team_create
2. CREATE TASKS → One task_create per work unit (be specific and atomic)
3. SPAWN AGENTS → Each agent gets its own context, model, session
4. PARALLEL WORK → Agents execute independently without sharing context
5. COMMUNICATE → Agents report results via send_message
6. DELETE TEAM → Clean shutdown with team_delete (forces context reset)

## Orchestrator Rules
- The primary agent ONLY orchestrates — it does not do the work itself
- Keep the orchestrator's context window lean (target <40% usage)
- Each sub-agent should have a single, clear objective
- Sub-agents should be deleted after completing their task
- Use ad hoc teams for follow-up work rather than reusing existing agents
- Always provide sub-agents with the skills and slash commands they need

## Prompt Engineering Triggers
Use these information-dense keywords to activate specific behaviors:
- "Build a new agent team" → triggers team_create + task assignment
- "Work in parallel" → triggers concurrent agent spawning
- "Report back" → triggers send_message to orchestrator
- "Spin up a new agent team to do this work" → ad hoc team creation
- "Give them all the context they need" → ensures skill/command propagation

## Context Engineering Best Practices
- Each sub-agent runs skills independently (they don't inherit parent context)
- Explicitly tell sub-agents which skills and /commands to run
- Delete teams after work completes to prevent context rot
- The task list is the centralized hub — everything kicks off from it
- Use T-Mux for visual observability of agent panes

## Error Recovery
When sub-agents fail or produce incomplete results:
- Do NOT have the orchestrator fix it directly
- Spin up a NEW ad hoc agent team for the fix
- Give the new team all context about what went wrong
- This maintains clean context separation