GitHub - heurema/teams-field-guide: Claude Code Agent Teams — Field Guide. Bugs, workarounds, orchestration patterns, ecosystem.

   __                                  _____      __    __                  _     __
  / /____  ____ _____ ___  _____      / __(_)__  / /___/ /     ____ ___  __(_)___/ /__
 / __/ _ \/ __ `/ __ `__ \/ ___/_____/ /_/ / _ \/ / __  /_____/ __ `/ / / / / __  / _ \
/ /_/  __/ /_/ / / / / / (__  )_____/ __/ /  __/ / /_/ /_____/ /_/ / /_/ / / /_/ /  __/
\__/\___/\__,_/_/ /_/ /_/____/     /_/ /_/\___/_/\__,_/      \__, /\__,_/_/\__,_/\___/
                                                            /____/

Production reference for Claude Code multi-agent systems.

Subagents, Agent Teams, configuration schemas, known bugs, orchestration patterns, and cost optimization. For multi-model teams, see arbiter.

Install as Claude Code Skill

One-liner:

git clone https://github.com/Real-AI-Engineering/teams-field-guide.git ~/.claude/skills/teams-field-guide && ln -s ~/.claude/skills/teams-field-guide/skills/teams-advisor ~/.claude/skills/teams-advisor

Verify: restart Claude Code, then ask "which agent system should I use?" — the teams-advisor skill should activate and walk you through the decision tree.

Update:

cd ~/.claude/skills/teams-field-guide && git pull

Uninstall:

rm ~/.claude/skills/teams-advisor && rm -rf ~/.claude/skills/teams-field-guide

The skill activates automatically on queries about agent teams, subagents, multi-agent patterns, team bugs, or orchestration.

1. Requirements & Version Support

Minimum version: Claude Code v2.1.45 for full custom agent support (memory:, TeammateIdle/TaskCompleted hooks, Task(agent_type) syntax).

Agent Teams (experimental): Requires the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Version Compatibility Matrix

Version	Multi-Agent Changes
v2.1.33	Fixed tmux teammate messaging; fixed false "not available on plan" warning
v2.1.41	Guard against launching Claude inside Claude
v2.1.43	Fixed wrong model identifier for Bedrock/Vertex/Foundry
v2.1.45	`TeammateIdle`/`TaskCompleted` hooks; `Task(agent_type)` syntax; `memory` field in agent frontmatter
v2.1.47	Fixed `model` in `.claude/agents/` being ignored for teammates; fixed agents not discovered from worktrees; `last_assistant_message` in Stop/SubagentStop hooks
v2.1.49	`--worktree`/`-w` CLI flag; `isolation: worktree`; `background: true`; `claude agents` CLI command; `ConfigChange` hook
v2.1.50	`WorktreeCreate`/`WorktreeRemove` hooks; memory leak fix for completed teammate tasks

2. TL;DR — Which System to Use

Do agents need to talk directly to each other?
    |
    +--> YES:  Agent Teams (TeamCreate + SendMessage)
    |          Experimental. Has known bugs. Use only when
    |          peer-to-peer messaging is genuinely required.
    |
    +--> NO: Do you need per-agent tools, skills, or hooks?
                |
                +--> YES:  Custom Agents + parallel Task() calls
                |          Full configuration, stable, no Teams bugs.
                |          Recommended for most production use cases.
                |
                +--> NO:   Parallel Task() calls (general-purpose)
                           Simplest and cheapest option.
                           All agents use lead's configuration.

Recommendation: The hybrid approach — define agents in .claude/agents/ and launch them via parallel Task() calls — gives you full per-agent configuration (tools, model, skills, hooks, memory) without any of the Agent Teams instability. Use Agent Teams only when agents genuinely must exchange messages with each other.

3. Two Systems Compared

	Subagents (Parallel Tasks)	Agent Teams
Status	Stable, production-ready	Experimental (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
Communication	Worker returns result to parent only	Mesh: any agent can message any other directly
Coordination	Parent manages all sequencing	Shared task list; agents self-organize
Per-agent config	Full: tools, model, hooks, memory, skills, permissions	Minimal: spawn prompt only (most config broken or ignored)
Cost	Lower — summary returned to parent	~3-7x higher — each teammate holds full context window
Best for	Focused delegation, independent parallel work, isolation	Parallel research, competing hypotheses, peer coordination

4. Custom Agents Reference

Custom agents are defined as Markdown files with YAML frontmatter. The file body is the agent's system prompt. Store them in .claude/agents/ (project-scoped) or ~/.claude/agents/ (user-scoped).

Frontmatter Schema

Field	Required	Type	Default	Description
`name`	Yes	string	—	Unique identifier. Use lowercase letters and hyphens only.
`description`	Yes	string	—	Tells Claude when to auto-delegate. Write "Use when..." with concrete examples.
`tools`	No	string or array	inherit all	Allowlist of permitted tools. Use `Task(agent1, agent2)` to restrict which subagents this agent can spawn.
`disallowedTools`	No	string or array	none	Denylist. Removed from the inherited tool set.
`model`	No	string	inherit	`sonnet`, `opus`, `haiku`, or `inherit`.
`permissionMode`	No	string	inherited	`default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan`.
`maxTurns`	No	integer	unlimited	Maximum agentic turns before the agent stops.
`skills`	No	list	none	Skills loaded at agent startup. Listed skills are fully injected (not lazy). Unlisted skills are invisible to the agent.
`mcpServers`	No	list	inherited	MCP servers available to this agent. String reference or inline `{name: config}` object.
`hooks`	No	object	none	Lifecycle hooks scoped to this agent. Note: only 6 of the 16 hook types work in agent frontmatter: `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PostToolUseFailure`, `Stop`, `SubagentStop` (see Experimental Features).
`memory`	No	string	none	`user`, `project`, or `local`. Enables persistent cross-session memory. First 200 lines of `MEMORY.md` are auto-injected.
`background`	No	boolean	false	Always run as a background task. Added v2.1.49.
`isolation`	No	string	none	`worktree` — run in an isolated git worktree with auto-cleanup. Added v2.1.49.
`color`	No	string	—	UI color in the terminal: `green`, `cyan`, `red`, `blue`, `yellow`, `magenta`.

Example Agent Definition

---
name: security-reviewer
description: |
  Use this agent when code needs security review, vulnerability assessment,
  or OWASP compliance checking.
  <example>
  user: "Check the auth module for vulnerabilities"
  assistant: "I'll use security-reviewer agent to audit src/auth/"
  </example>
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: sonnet
permissionMode: plan
maxTurns: 30
skills:
  - api-conventions
memory: project
color: red
---

You are a senior security engineer. Focus on OWASP Top 10, injection
vulnerabilities, authentication flaws, and secrets in code. Report
findings with severity (critical/high/medium/low) and a specific fix.

Context Rules

Agents are isolated by design. What an agent does and does not see:

Receives: its own system prompt (file body) + basic environment info + CLAUDE.md from the project
Does NOT receive: parent conversation history
Does NOT receive: parent's Claude Code system prompt
Does NOT receive: skills loaded by the parent (must be listed in the agent's own skills: field)
Loads fresh: project's CLAUDE.md and git status

Tools Field Syntax

# Allowlist — agent can only use these tools
tools: Read, Glob, Grep, Bash

# Restrict which subagents this agent can spawn
tools: Task(worker, researcher), Read, Bash

# If Task is omitted entirely, the agent cannot spawn any subagents

Available tool names: Read, Write, Edit, Bash, Glob, Grep, Task, WebFetch, WebSearch, NotebookRead, NotebookEdit, LS, KillShell, BashOutput, TodoWrite, plus any MCP tool names.

Critical: use tools: not allowed-tools:. The wrong field name silently grants ALL tools. See Known Limitations.

Memory Field

memory: user     # ~/.claude/agent-memory/<name>/         (shared across all projects)
memory: project  # .claude/agent-memory/<name>/           (git-tracked, project-specific)
memory: local    # .claude/agent-memory-local/<name>/     (gitignored, local only)

When a memory location is configured, the first 200 lines of MEMORY.md in that directory are automatically injected into the agent's context. Read, Write, and Edit are automatically enabled for the memory path.

Discovery Priority

Location	Scope	Priority
`--agents` CLI JSON flag	Current session only	1 (highest)
`.claude/agents/`	Project (git-committable)	2
`~/.claude/agents/`	User (all projects)	3
Plugin `agents/` directory	Per installed plugin	4 (lowest)

CLI Ephemeral Agents

Agents can be defined inline without a file, useful for one-off sessions:

claude --agents '{
  "reviewer": {
    "description": "Reviews code for security vulnerabilities",
    "prompt": "You are a security expert...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "opus",
    "maxTurns": 30
  }
}'

Managing Agents

claude agents    # List all discovered agents from CLI
/agents          # Interactive TUI: view, create, edit, delete agent files

5. Agent Teams Setup

Agent Teams enable mesh communication between agents — each teammate can send messages directly to any other. This comes at significant cost and stability tradeoffs.

Activation

// .claude/settings.json or ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "auto"
}

teammateMode options: auto (Claude picks the best available display), tmux, in-process.

The 7 Core Tools

Tool	Purpose
`TeamCreate`	Create a named team; writes `~/.claude/teams/{name}/config.json`
`TaskCreate`	Add a task to the team's shared task list
`TaskUpdate`	Update task status, owner, or dependencies
`TaskList`	List all tasks (used by workers to claim available work)
`Task(team_name=)`	Spawn a teammate into the named team
`SendMessage`	Send a message to one or all teammates
`TeamDelete`	Tear down the team and clean up resources

SendMessage Types

Type	Behavior
`message`	Targeted direct message to one named teammate
`broadcast`	Sent to all active teammates simultaneously (costs N times as much)
`shutdown_request` / `shutdown_response`	Graceful coordinated teardown
`plan_approval_response`	Approve or reject a teammate's proposed plan

Display Modes

Mode	Navigation Keys	Requirements
`in-process`	Shift+Up/Down (switch agents), Enter (select), Esc (back), Ctrl+T (team view)	Any terminal
`tmux`	Standard tmux pane navigation	tmux installed
`iterm2`	Split pane navigation	iTerm2 + `it2` CLI tool

Not supported: VS Code terminal, Windows Terminal, Ghostty, Zellij, WezTerm.

Team-Specific Hooks

Hook Event	Fires When	Blocking?
`TeammateIdle`	A teammate signals it is going idle	Yes — exit code 2 keeps the teammate working
`TaskCompleted`	A task is marked as done in the shared list	Yes — exit code 2 keeps the task open
`SubagentStart`	A subagent spawns	No
`SubagentStop`	A subagent finishes	Yes

Environment Variables Set on Teammates

When a teammate is spawned, these environment variables are set in its process:

CLAUDE_CODE_TEAM_NAME           # Name of the team this agent belongs to
CLAUDE_CODE_AGENT_ID            # Unique agent identifier (name@team-name format)
CLAUDE_CODE_AGENT_NAME          # Human-readable agent name
CLAUDE_CODE_AGENT_TYPE          # Agent type (e.g., "general-purpose")
CLAUDE_CODE_PLAN_MODE_REQUIRED  # Whether plan mode is enforced
CLAUDE_CODE_PARENT_SESSION_ID   # Session ID of the lead agent

File System Layout

~/.claude/
├── teams/{team-name}/
│   ├── config.json           # members[], leadAgentId, leadSessionId
│   └── inboxes/              # Per-agent message queues
├── tasks/{team-name}/
│   └── {id}.json             # Individual task files
└── agents/
    └── *.md                  # Custom agent definitions

6. Per-Agent Customization Matrix

Capability	Subagents (Custom Agents + Tasks)	Agent Teams
Custom system prompt	Via `.claude/agents/*.md` body	Spawn prompt (natural language only)
Tools allowlist	`tools:` field	⚠️ Broken — agents lose tools when spawned with `team_name` (#25608)
Tools denylist	`disallowedTools:` field	⚠️ Broken
Model selection	`model:` field	`model=` parameter on Task (⚠️ unreliable for in-process teammates, fixed in v2.1.47 for `.claude/agents/`)
Skills	`skills:` field (explicit list)	Inherited from project (no per-agent control)
MCP servers	`mcpServers:` field	Inherited (no per-agent control)
Hooks	`hooks:` in frontmatter	⚠️ Broken — session ID mismatch prevents firing (#27655)
Persistent memory	`memory: user/project/local`	Not supported
Permission mode	`permissionMode:` field	Post-spawn only (workaround required)
Max turns	`maxTurns:` field	Not supported
Git isolation	`isolation: worktree`	Not supported
Background mode	`background: true`	Not supported

7. Orchestration Patterns

Pattern 1: Parallel Specialists

Run multiple independent reviewers simultaneously, each with a different lens. Results are returned to the lead for synthesis.

When to use: Code review, multi-angle analysis, parallel audits.

# Launch all reviewers simultaneously (run_in_background=True)
Task(subagent_type="security-reviewer", model="sonnet", run_in_background=True,
     prompt="Review src/auth/ for OWASP Top 10 vulnerabilities")

Task(subagent_type="perf-analyst", model="sonnet", run_in_background=True,
     prompt="Profile src/api/ for latency and memory issues")

Task(subagent_type="test-writer", model="sonnet", run_in_background=True,
     prompt="Write unit tests for src/auth/ targeting edge cases")

# Wait for all three, then synthesize findings

Pattern 2: Dependency Wave

Execute tasks in parallel batches where each batch depends on the previous one completing. Avoids sequential bottlenecks while respecting true dependencies.

When to use: Build pipelines, staged migrations, multi-phase feature development.

# Wave 1 — independent modules (parallel)
Task(model="sonnet", run_in_background=True, prompt="Build module A")
Task(model="sonnet", run_in_background=True, prompt="Build module B")
Task(model="sonnet", run_in_background=True, prompt="Build module C")
# Wait for all wave 1 tasks

# Wave 2 — depends on wave 1 output (parallel)
Task(model="sonnet", run_in_background=True, prompt="Integrate module A and B")
Task(model="opus",   run_in_background=True, prompt="Architecture review of all modules")

Pattern 3: Self-Organizing Swarm

Workers poll a shared task list and atomically claim unclaimed work. No central dispatcher needed — the task list is the coordination mechanism.

When to use: Large backlogs of independent tasks, processing queues, workloads of unknown size.

TeamCreate(team_name="file-processor")

# Add many tasks to the shared list
for file in file_list:
    TaskCreate(subject=f"Process {file}", description=f"Extract and transform {file}")

# Spawn workers that self-direct
for i in range(4):
    Task(team_name="file-processor", model="sonnet",
         prompt="Poll TaskList for unclaimed tasks. Claim one, complete it, repeat until no tasks remain.")

Note: Use safe-task-claim to prevent race conditions when multiple workers claim the same task.

Pattern 4: Competing Hypotheses

Multiple agents simultaneously test different approaches to the same problem. The lead evaluates results and picks the winner (or synthesizes the best elements from each).

When to use: Uncertain implementation approach, algorithm selection, architectural trade-offs.

Task(model="sonnet", run_in_background=True,
     prompt="Implement the caching layer using Redis. Write full implementation + benchmarks.")

Task(model="sonnet", run_in_background=True,
     prompt="Implement the caching layer using in-memory LRU. Write full implementation + benchmarks.")

Task(model="sonnet", run_in_background=True,
     prompt="Implement the caching layer using a CDN-first approach. Write full implementation + benchmarks.")

# Lead compares benchmark results and chooses

Pattern 5: Council / Debate

Agents independently propose approaches, then the lead (or an opus agent) synthesizes them into a consensus design. Avoids anchoring bias from a single proposal.

When to use: Architecture decisions, API design, major refactors.

# Proposal phase — parallel
Task(model="sonnet", run_in_background=True,
     prompt="Propose a database schema for the orders system. Justify trade-offs.")
Task(model="sonnet", run_in_background=True,
     prompt="Propose a database schema for the orders system from a read-performance perspective.")
Task(model="sonnet", run_in_background=True,
     prompt="Propose a database schema for the orders system prioritizing write throughput.")

# Synthesis phase — single opus agent reviews all proposals
Task(model="opus", prompt="Here are three schema proposals: [A] [B] [C]. Synthesize the best design.")

Pattern 6: Plan-First

Generate a detailed plan before spawning any implementation agents. Planning costs ~10K tokens; a swarm costs ~800K tokens. Catching a bad plan early is far cheaper than discarding work.

When to use: Any non-trivial feature; whenever scope is ambiguous.

# Phase 1 — plan (cheap, ~10K tokens)
plan = Task(model="opus",
            prompt="Create a detailed step-by-step implementation plan for: [feature description]. "
                   "Output JSON: {steps: [{id, title, files_affected, dependencies}]}")

# Phase 2 — implement in parallel (expensive, ~800K tokens)
for step in plan.steps:
    Task(model="sonnet", run_in_background=True,
         isolation="worktree",
         prompt=f"Implement step {step.id}: {step.title}. Files: {step.files_affected}")

Pattern 7: Adversarial Review Loop

One agent implements, another critiques. The implementer revises based on critique. Cycle until the critic approves or the loop limit is reached.

When to use: High-stakes code, security-critical paths, complex algorithms.

revision = 0
approved = False

while not approved and revision < 3:
    Task(model="sonnet", prompt=f"Implement the payment processor. Previous critique: {critique}")
    critique = Task(model="sonnet", subagent_type="security-reviewer",
                    prompt="Review this implementation. Output: APPROVED or CHANGES_NEEDED + list of issues.")
    approved = "APPROVED" in critique
    revision += 1

Pattern 8: Codebase-Mediated Coordination

Agents coordinate through shared code and documentation rather than direct messages. File ownership boundaries are defined in CLAUDE.md. Each agent owns specific directories; they read shared contracts (interfaces, schemas) but never touch each other's files.

When to use: Large parallel builds, 5+ agent teams, any scenario where peer messaging is error-prone.

# In CLAUDE.md (the shared contract every agent reads):
# Module Ownership:
# - Agent "api-builder": owns src/api/ only
# - Agent "frontend-dev": owns src/ui/ only
# - Agent "db-layer": owns src/db/ only
# - Shared interfaces in src/contracts/ — read by all, written by none

No SendMessage calls needed. Each agent reads CLAUDE.md, knows its boundaries, and coordinates through the git repository.

Pattern 9: Two-Layer Agent Definitions

Separate the persistent HOW (agent identity, skills, tools — defined in .claude/agents/*.md) from the ephemeral WHAT (task-specific instructions passed at spawn time). This avoids duplicating configuration while enabling reuse across many different tasks.

When to use: Reusable specialist agents deployed across many sessions or projects.

# .claude/agents/backend-engineer.md defines:
#   model: sonnet, tools: [Read, Write, Edit, Bash, Grep],
#   skills: [api-conventions, db-patterns], memory: project
#   System prompt: "You are a backend engineer specializing in Go..."

# At spawn time, pass only WHAT (task-specific)
Task(subagent_type="backend-engineer", run_in_background=True,
     prompt="Implement the order processing endpoint per the spec in docs/orders-api.md")

Task(subagent_type="backend-engineer", run_in_background=True,
     prompt="Refactor the payment service to use the new retry library")

8. Known Limitations & Workarounds

Last verified: 2026-02-23. Check linked issues for current status.

Limitation	Issue	Workaround
`model=` silently ignored for in-process teammates (all run at lead's model)	#27038	Fixed in v2.1.47 for `.claude/agents/` — update to latest
Custom agents lose their `tools` list when spawned with `team_name`	#25608	Use custom agents + parallel `Task()` calls instead of Teams
Agent frontmatter hooks don't fire in teams (session ID mismatch)	#27655	Use custom agents + parallel `Task()` calls instead of Teams
`allowed-tools:` (wrong field name) silently grants ALL tools	#27099	Use `tools:` (no `allowed-` prefix)
`/resume` does not restore teammates	#26323	No workaround; avoid using `/resume` in team sessions
Zombie teammates remain after `TeamDelete`	#26955	Kill processes manually; claude-code-teams-mcp has `force_kill_teammate`
Plan mode auto-approves before lead reviews	#27265	Do not use `plan_approval_response` until fixed
Bedrock: 400 errors from normalized model ID	#25193	Fixed in v2.1.43 — update
Vertex AI: agent teams fail to launch	#27729	No workaround yet; use standard API
`PreToolUse` hooks not inherited by subagents (security gap)	#21460	Define hooks in agent frontmatter; validate in agent's own system prompt
Auto memory race condition with concurrent teams	#24130	Use `memory: local` per agent; avoid shared memory in concurrent teams
`CLAUDE_CONFIG_DIR` not passed to teammate processes	#24989	Set in global environment; avoid relying on custom config paths in teams
`CLAUDE_PROJECT_DIR` empty in subagent environments	#26429	Pass project path explicitly in agent prompt
Deferred MCP tools unavailable in custom agents	#25200	Use non-deferred (eager) MCP tool configuration
`SubagentStart`/`SubagentStop` hooks have unreliable delivery	#27153	Do not rely on these hooks for critical logic
`--agent` key in `settings.json` causes `Task` tool to disappear in Teams	#13533	Rename key to `_agent` temporarily to disable
~37 agent limit: silently stops loading after ~37 agents, no error	#18993	Keep total agent definitions below 37; consolidate with broader descriptions

Additional Known Gotchas

These are behavioral quirks that are not bugs per se but will trip you up:

Delegate Mode first in Agent Teams. Press Shift+Tab immediately after spawning teammates. If you do not, the lead agent will claim implementation tasks from the shared list before teammates can.
File ownership is the #1 rule. Two agents editing the same file will silently overwrite each other's changes. Define explicit directory boundaries per agent in CLAUDE.md.
Plan mode is irreversible per teammate session. Once a teammate is in plan mode, it cannot switch to execution mode. Spawn a new teammate for implementation.
Agents spawn sequentially. Each agent takes 6-7 seconds to initialize. A team of 5 agents takes ~35 seconds before all are active.
Teammates do not see each other's text output. The only way to share information between teammates is via SendMessage or through files written to the shared codebase.
bypassPermissions for teammates requires setting it in ~/.claude/settings.json (global), not project-level settings (#26479).
Git worktree path access requires adding additionalDirectories: ["../worktree-prefix-*"] to permissions (#12748).
User-level custom agents (~/.claude/agents/) cannot be used as subagent_type in Task calls. Project-level agents (.claude/agents/) can be referenced by name. Plugin agents (e.g., superpowers:code-reviewer) also work. If your user-level agent isn't found, use subagent_type="general-purpose" and inline the system prompt.

9. Experimental Features

The following features work in current versions but are not documented in official Anthropic docs. They may change or be removed without notice.

`skills:` in Agent Frontmatter

⚠️ Undocumented but confirmed working.

skills:
  - api-conventions
  - db-patterns

Restricts which skills the agent sees. Unlisted skills are invisible to the agent. Useful for reducing context bloat — agents with focused skill sets perform better on specialized tasks.

`color:` in Agent Frontmatter

⚠️ Undocumented but confirmed working.

color: cyan   # Options: blue, cyan, green, yellow, magenta, red

Sets the agent's color indicator in the terminal UI. Purely cosmetic; no behavioral effect.

`background: true`

⚠️ Added in v2.1.49. Not in official docs.

background: true

The agent always runs as a background task regardless of how it is invoked. Useful for monitoring and observer agents.

`isolation: worktree`

⚠️ Added in v2.1.49. Not in official docs.

isolation: worktree

Runs the agent in an isolated git worktree. The worktree is created at agent start and cleaned up automatically when the agent finishes. Prevents agents from conflicting on shared files. Custom branch name not yet supported (#27749).

`use-when:` in Skill Frontmatter

⚠️ Does not work. Despite appearing in some community examples, the use-when: field in skill frontmatter is not functional (#27569). Use the description: field instead to control when a skill is triggered.

Working Hooks in Agent Frontmatter

⚠️ Only 6 of the 16 hook event types fire correctly when defined in agent frontmatter hooks:. The 6 that work:

PreToolUse
PostToolUse
PermissionRequest
PostToolUseFailure
Stop
SubagentStop

The remaining 10 hook types (e.g., TeammateIdle, TaskCompleted, SubagentStart, ConfigChange, WorktreeCreate, WorktreeRemove, and others) must be defined in settings.json at the project or user level and do not fire from agent frontmatter.

~37 Agent Limit

⚠️ Undocumented hard limit.

Claude Code silently stops loading agent definitions after approximately 37 agents. No error is raised. If you have a large agent collection and some agents seem to go missing, this is likely the cause (#18993).

Skill-Agent Binding

⚠️ Undocumented combination.

# In a skill's SKILL.md frontmatter:
---
context: fork
agent: my-specialist-agent
---

Binds a skill invocation to a specific agent. agent: without context: fork does not work. context: fork without agent: creates a fork without agent binding.

Dynamic Context Injection via SubagentStart Hook

⚠️ Undocumented but functional in some versions.

A SubagentStart hook can read the agent_type field from the hook input, look up role-specific configuration, and return hookSpecificOutput.additionalContext to inject role-specific context before the agent begins. For teammates, the name parameter becomes agent_type when no matching agent definition exists.

Hidden Environment Variables

Beyond the 6 documented team environment variables, these additional vars are available:

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1   # Disable all background tasks globally
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50       # Trigger context compaction earlier (default ~80%)

13 TeammateTool Operations

The internal TeammateTool API has 13 operations, more than the 7 documented tools expose:

spawnTeam, discoverTeams, requestJoin, approveJoin, rejectJoin,
write, broadcast, requestShutdown, approveShutdown, rejectShutdown,
approvePlan, rejectPlan, cleanup

These are accessible via claude-code-teams-mcp, which reimplements the full protocol.

Undocumented CLI Flags for Teammate Spawning

The exact command Claude Code uses internally to spawn a teammate (discovered via binary analysis):

CLAUDECODE=1 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 \
claude \
  --agent-id "worker-1@my-team" \
  --agent-name "worker-1" \
  --team-name "my-team" \
  --agent-color "blue" \
  --parent-session-id "..." \
  --agent-type "general-purpose" \
  --model "sonnet"
  # Optional flags:
  # --plan-mode-required
  # --dangerously-skip-permissions

10. Cost Optimization

Model Distribution

Model	Cost	Use For	Never For
opus	$$$	Architecture decisions, synthesis of competing results, critical trade-offs	Bulk research, code review, data gathering, formatting
sonnet	$$	Research, implementation, writing, editing, code review	Final architecture decisions
haiku	$	Trivial lookups, formatting, line counts, simple grep-and-report	Complex reasoning, security analysis, nuanced decisions

Decision rule: Architecture / synthesis → opus. Volume / review → sonnet. Simple mechanical tasks → haiku.

On code review specifically: Sonnet is approximately 4-6x cheaper than Opus at list pricing. For structured review tasks like code review, sonnet with a focused skill produces comparable or better results — particularly for security issue detection where a narrower focus reduces false negatives. Use sonnet for all code review tasks.

Practical Tips

write() over broadcast() in Teams. broadcast delivers to N teammates and costs N times as much. Use targeted SendMessage with type: message unless you genuinely need all agents to receive the information.
Plan before spawning. A planning phase costs ~10K tokens. A spawned swarm costs ~800K tokens. Catching a design flaw in planning saves the entire swarm cost.
Pre-approve tools. Add expected tool patterns to permissions.allow in settings before starting a team. This prevents permission approval storms that stall every agent.
Trigger compaction early for subagents. Set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 to compact context at 50% instead of the default ~80%. Prevents context overflow in long-running agents.
Cap team size. Beyond 4-5 parallel agents, returns diminish and coordination overhead increases. Prefer 3-5 focused agents over 8+ generalist agents.
Use isolation: worktree selectively. Worktree isolation prevents file conflicts but adds overhead. Use it only when agents edit overlapping files.

Benchmark Numbers

Source: alexop.dev, 2026:

Solo agent: ~200K tokens per complex task
3 subagents (parallel Tasks): ~440K tokens total
3-person Agent Team: ~800K tokens total

Source: Daytona benchmark, 2026:

Agents in sandboxed environments use ~40% of the context window vs ~80-90% for a solo agent handling the same task (due to cleaner context, no accumulated history).

The implication: Agent Teams cost approximately 3-7x more than parallel Task calls for the same work. Use Teams only when peer communication genuinely provides value that offsets this cost.

11. Case Studies

Anthropic C Compiler (Official)

Anthropic's engineering team built a C compiler using 16 agents running 2,000 sessions over two weeks at a total cost of approximately $20,000, producing ~100,000 lines of code.

The architecture used a bare git repository as the coordination point, with each agent cloning the repository into /workspace. A current_tasks/ directory served as a file-lock mechanism, preventing agents from duplicating work. There was no central orchestrator — agents simply identified "the next obvious problem" from the test output and worked on it. The team discovered that the quality of the test harness mattered more than the agents themselves: "the task verifier must be nearly perfect." A --fast flag randomly sampled 1-10% of tests during development to reduce feedback latency.

Lessons:

Test harness quality is the ceiling for agent quality — invest heavily in it
File-based coordination (a directory as a lock) works well at scale without complex messaging
No central orchestrator can work; agents can self-direct given clear criteria
Random test sampling during development cuts wait time significantly

24-Agent Local Hardware (Community)

A community engineer ran 24 simultaneous Claude Code agents on local hardware, using a Rust/Tokio orchestrator and a local Mistral 7B model on an RTX 4070. Coordination happened entirely through the shared codebase — no direct agent messaging. CLAUDE.md defined module ownership boundaries. The result: 683 tests, zero failures, a 1.53:1 test-to-production-code ratio, enforced by pre-commit hooks that blocked any commit not meeting the ratio threshold.

Lessons:

Codebase-mediated coordination scales to 24 agents without peer messaging
Pre-commit hooks are an effective quality gate that agents cannot bypass
Local models are viable for subagent workloads when latency is less critical
File ownership boundaries defined in CLAUDE.md prevent silent overwrites at scale

E-commerce Agent Teams Failure (Community)

A developer ran a 5-person Agent Team for two days on an e-commerce project. The lead agent "forgot to coordinate half the tasks" — a consequence of context filling up and the coordination state being lost. The result was 100,000+ tokens consumed with an incomplete, inconsistent codebase.

Lessons:

Context independence is a strength for divergent work but a weakness for convergent work requiring continuous coordination
Plan-First pattern (Pattern 6) would have caught the coordination gap early
For convergent tasks (building one coherent system), codebase-mediated coordination (Pattern 8) is more reliable than relying on agent memory
Agent Teams' lack of a persistent shared state makes them unsuitable for long-running projects without an external coordination mechanism

12. Ecosystem

Top projects by usefulness and community adoption:

Project	Stars	Description
steveyegge/gastown	10k	Multi-agent workspace manager with Beads issue tracking integration
Yeachan-Heo/oh-my-claudecode	7k	32 agents, 40+ skills, smart model routing, Autopilot and Ultrapilot modes
EveryInc/compound-engineering-plugin	9.4k	Official plugin with `/work` command and pre-built team workflows
danielmiessler/Personal_AI_Infrastructure	9k	PAI v3.0 — Algorithm/Engineer subagent architecture
cs50victor/claude-code-teams-mcp	181	Standalone MCP reimplementation of the Agent Teams protocol; enables mixed Claude + OpenCode teams
modu-ai/moai-adk	750	Agent Development Kit with typed team roles (backend-dev, frontend-dev, tester)
alinaqi/claude-bootstrap	508	Scaffolds agent teams by default in every new project
jayminwest/overstory	—	Coordinator → Supervisor → Workers hierarchy with SQLite-based message passing and 4-tier conflict resolution
Ruya-AI/cozempic	98	Context pruning that protects team coordination state
Osso/safe-task-claim	—	Atomic task claiming MCP server — prevents race conditions in swarm patterns

See docs/ecosystem.md for the full catalog of 30+ projects, guides, and resources.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
docs		docs
skills/teams-advisor		skills/teams-advisor
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Install as Claude Code Skill

Table of Contents

1. Requirements & Version Support

Version Compatibility Matrix

2. TL;DR — Which System to Use

3. Two Systems Compared

4. Custom Agents Reference

Frontmatter Schema

Example Agent Definition

Context Rules

Tools Field Syntax

Memory Field

Discovery Priority

CLI Ephemeral Agents

Managing Agents

5. Agent Teams Setup

Activation

The 7 Core Tools

SendMessage Types

Display Modes

Team-Specific Hooks

Environment Variables Set on Teammates

File System Layout

6. Per-Agent Customization Matrix

7. Orchestration Patterns

Pattern 1: Parallel Specialists

Pattern 2: Dependency Wave

Pattern 3: Self-Organizing Swarm

Pattern 4: Competing Hypotheses

Pattern 5: Council / Debate

Pattern 6: Plan-First

Pattern 7: Adversarial Review Loop

Pattern 8: Codebase-Mediated Coordination

Pattern 9: Two-Layer Agent Definitions

8. Known Limitations & Workarounds

Additional Known Gotchas

9. Experimental Features

skills: in Agent Frontmatter

color: in Agent Frontmatter

background: true

isolation: worktree

use-when: in Skill Frontmatter

Working Hooks in Agent Frontmatter

~37 Agent Limit

Skill-Agent Binding

Dynamic Context Injection via SubagentStart Hook

Hidden Environment Variables

13 TeammateTool Operations

Undocumented CLI Flags for Teammate Spawning

10. Cost Optimization

Model Distribution

Practical Tips

Benchmark Numbers

11. Case Studies

Anthropic C Compiler (Official)

24-Agent Local Hardware (Community)

E-commerce Agent Teams Failure (Community)

12. Ecosystem

13. Contributing

14. Sources

Official

Community Guides

Key Gists

Hacker News Threads

See Also

15. Changelog

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

`skills:` in Agent Frontmatter

`color:` in Agent Frontmatter

`background: true`

`isolation: worktree`

`use-when:` in Skill Frontmatter

Packages