AI Fleet Findings¶
Researched 2026-04-14 by Chief Director
1. Agent Teams (Experimental): Native Multi-Agent Coordination¶
Built-in peer-to-peer multi-agent with a lead coordinator. Agents message each other directly, claim tasks autonomously, work in parallel.
Enable:
// ~/.claude/settings.json or project settings
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
CLI:
Key features: - Shared task list with automatic dependency management - Direct inter-agent messaging (not just parent→child) - Parallel exploration, each teammate has own context window - Lead-based coordination, one session acts as team lead - Autonomous task claiming, teammates self-select work
Limitations: - No session resumption with in-process teammates - Task status can lag - One team per session - No nested teams (teammates can't spawn their own teams) - Lead is fixed (can't promote teammate to lead) - Higher token usage, each teammate is a full Claude instance
Best for: Complex coordination, research, code review, cross-layer work
Docs: https://code.claude.com/docs/en/agent-teams
2. Agent SDK: Programmatic Multi-Agent Control¶
Python/TypeScript library. Claude Code's capabilities as a library, same tools, same agent loop, but programmable.
Install:
Multi-agent patterns:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async def main():
async for message in query(
prompt="Use the code-reviewer agent to review this codebase",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer",
prompt="Analyze code quality...",
tools=["Read", "Glob", "Grep"]
)
}
)
):
print(message)
Session persistence:
# Capture session ID from first query
session_id = None
async for message in query(prompt="Start analysis", ...):
if message.type == "system" and message.subtype == "init":
session_id = message.data["session_id"]
# Resume with full context
async for message in query(
prompt="Continue with findings",
options=ClaudeAgentOptions(resume=session_id)
):
print(message)
Hooks for inter-agent coordination:
async def validate_and_route(input_data, tool_use_id, context):
return {}
ClaudeAgentOptions(
hooks={
"UserPromptSubmit": [
HookMatcher(matcher="pattern", hooks=[validate_and_route])
]
}
)
Best for: Production, CI/CD, custom logic, programmatic agent spawning
Docs: https://code.claude.com/docs/en/agent-sdk/overview
3. Pipe Mode + Stream JSON: Chainable Agents¶
Non-interactive mode with JSON input/output for chaining multiple agents via Unix pipes.
CLI flags:
claude -p "prompt" [options]
--output-format json # Single JSON response
--output-format stream-json # Newline-delimited JSON stream
--input-format stream-json # Accept streaming JSON input
--json-schema '{...}' # Validate output against schema
--bare # Skip auto-discovery, reduce startup time
--resume [session_id] # Resume by session ID
Agent chaining:
claude -p "Analyze this codebase" \
--output-format stream-json | \
claude -p "Review this analysis for issues" \
--input-format stream-json \
--output-format stream-json | \
claude -p "Create a summary of all findings" \
--input-format stream-json
Session resume in scripts:
session_id=$(claude -p "Start analysis" --output-format json | jq -r '.session_id')
claude -p "Continue with findings" --resume "$session_id" --output-format json
Best for: Scripting, CI, lightweight chains, low-cost delegation
4. Managed Agents API: Hosted Serverless Agents¶
Fully hosted, serverless agent infrastructure from Anthropic.
- Runs in Anthropic's managed cloud containers
- Persistent sessions with server-side state
- Server-Sent Events (SSE) for streaming results
- Built-in sandboxing and permissions
- Multi-agent research preview (requires access request)
Pricing: $0.08 per session-hour + standard API token rates
Access: Requires managed-agents-2026-04-01 beta header
Docs: https://platform.claude.com/docs/en/managed-agents/overview
5. MCP Servers: Tool Integration Layer¶
Claude Code can act as an MCP server, and consume MCP servers for external tools.
claude mcp serve # Expose Claude Code as MCP server
claude mcp list # See configured servers
claude mcp add --transport http name url # Add HTTP server
claude mcp add name -- command args # Add stdio server
Multi-agent pattern: Each agent instance can access different MCP servers based on configuration.
6. Subagents: Built-in Single-Session Delegation¶
Custom subagent definitions:
# .claude/subagents/security-reviewer.md
> A specialized security auditor for authentication modules
---
System prompt and constraints here.
Tools: Read, Glob, Grep (no Edit/Write)
- Own context window
- Custom system prompts per subagent
- Independent tool allowlists
- Parent→child communication only (no peer messaging)
7. Full CLI Orchestration Flags¶
--agent <agent> # Use specific agent definition
--agents <json> # Define inline agents
--mcp-config <configs...> # Load MCP servers
--strict-mcp-config # Only use specified MCP servers
--allowed-tools <tools...> # Pre-approve tools
--disallowed-tools <tools...> # Block tools
--permission-mode <mode> # acceptEdits, auto, bypassPermissions, default, dontAsk, plan
--output-format <format> # text, json, stream-json
--input-format <format> # text, stream-json
--include-partial-messages # Stream tokens as generated
--json-schema <schema> # Validate output
--continue # Resume last conversation
--resume [value] # Resume by session ID
--session-id <uuid> # Use specific session ID
--fork-session # Create new instead of resuming
--worktree [name] # Git worktree for isolation
--tmux # Use tmux for split panes
--bare # Skip auto-discovery
--dangerously-skip-permissions # Bypass all permission checks
8. Comparison Matrix¶
| Approach | Parallelism | Communication | Context Cost | Setup | Best For |
|---|---|---|---|---|---|
| Agent Teams | High | Direct peer messaging | Very High (N × context) | One env var | Complex coordination, research |
| Subagents | Medium | Parent→child only | Medium | Define in .claude/ | Focused tasks, isolation |
| Agent SDK | High | Programmatic control | Very High | Python/TS | Production, CI/CD, custom logic |
| Managed Agents | High | API-driven | Very High | API calls | Long-running, production, async |
| Pipe Mode | Medium | Unix pipes (JSON) | Low per invocation | CLI + jq | Scripting, CI, lightweight chains |
| MCP Servers | N/A | Tool call access | Low | Configuration | External tool integration |
9. Architecture Implications for Forge¶
What to ditch: - tmux send-keys for agent communication (unreliable, breaks constantly) - Manual file-based inbox polling as primary comms method
What to adopt: - Agent Teams for interactive multi-agent work (directors coordinating managers) - Agent SDK for programmatic spawning (dispatcher, automations) - Pipe mode + stream-json for lightweight scripted chains - File bus (comms/) as async fallback and audit trail, not primary transport
Recommended stack: | Layer | Tool | Use Case | |-------|------|----------| | Interactive coordination | Agent Teams | Directors working with managers | | Programmatic orchestration | Agent SDK | Dispatcher, scheduled tasks, n8n integration | | Lightweight scripting | Pipe mode + stream-json | Quick chains, CI, cron jobs | | Async communication | comms/ file bus | Cross-session handoffs, audit trail | | External tools | MCP servers | Cloudflare, HA, Frigate integration |
Sources¶
- https://code.claude.com/docs/en/agent-teams
- https://code.claude.com/docs/en/sub-agents
- https://code.claude.com/docs/en/agent-sdk/overview
- https://platform.claude.com/docs/en/managed-agents/overview
- https://code.claude.com/docs/en/headless
- https://code.claude.com/docs/en/mcp
- https://shipyard.build/blog/claude-code-multi-agent/
[Claude Code]