Home › Entities › Agent Teams

Agent Teams

What it is

Agent Teams is Claude Code's multi-instance coordination layer that turns a single CLI into a parallel team of workers. It provides three distinct execution models (in-process, local async, and remote cloud), a 13-operation TeammateTool for the full team lifecycle, file-lock-based task claiming, per-agent mailbox communication, and git worktree isolation for parallel code editing.

Agent Teams is gated behind the tengu_amber_flint feature flag and not generally available. Each agent receives a color assignment and identity flags (--agent-name, --team-name) for UI differentiation.

Why it exists

Single-agent execution hits fundamental limits on complex tasks: one agent can't read 50 files, write 20 tests, and refactor 10 modules simultaneously. Agent Teams solves this with structured parallelism:

  1. Parallel investigation — multiple agents explore different parts of a codebase simultaneously
  2. Divide-and-conquer implementation — each agent takes a subset of changes, merges through git
  3. Cost optimization — the forked agent pattern achieves 92% prompt cache reuse, making 5 parallel agents cost nearly the same as 1

The design philosophy (from COORDINATOR_MODE's system prompt): "Parallelism is your superpower. Workers are async. Launch independent workers concurrently whenever possible — don't serialize work that can run simultaneously."

Three execution models

Model Isolation Use case
InProcessTeammate AsyncLocalStorage — same process, different context Lightweight, same terminal pane
LocalAgentTask Async background process Non-blocking parallel sub-agent
RemoteAgentTask Cloud container (CCR) Full cloud-sandboxed execution
Worktree isolation Git worktree — own branch and directory Parallel code editing without merge conflicts
DreamTask Background-only, memory-directory-only writes Memory consolidation (auto-dream)

AsyncLocalStorage provides implicit context isolation for in-process teammates without explicit parameter passing — each agent has its own storage namespace even though they share a Node.js process.

TeammateTool: 13 operations

Team setup: spawnTeam (creates ~/.claude/teams/{name}/), discoverTeams, cleanup

Membership: requestJoin, approveJoin, rejectJoin

Task coordination: TaskCreate (with blockedBy dependency declarations), TaskClaim (file-lock protected), TaskComplete (auto-unblocks dependent tasks)

Communication: SendMessage (direct), Broadcast (all teammates — cost scales with team size), requestShutdown, approveShutdown

Task claiming and file locking

The task list is a shared work queue stored as JSON files in ~/.claude/tasks/{team-name}/. Claiming uses file locking: writing current_tasks/parse_if_statement.txt prevents other agents from claiming the same work. Tasks have three states: pending, in-progress, completed. Completion auto-unblocks blockedBy dependencies.

Critical distinction: Locking applies to task claiming, not file writes. Two agents can simultaneously write to different source files. Merge conflicts during git operations are expected and resolved by the agents themselves.

Communication: mailbox system

Per-agent mailboxes at ~/.claude/teams/{name}/inboxes/{agent}.json. Structured message types include shutdown_request, plan_approval_response, and permission bubbling (teammates can escalate permission requests to the lead).

Git worktree isolation

When isolation: worktree is set, Claude Code creates a temporary git worktree: - Isolated: own working directory, staging area, HEAD - Shared: .git/objects/ (history stored once), .git/refs/ (branches visible to all)

Five simultaneous worktree agents produce five independent branches that merge through standard PR process. Cleanup is automatic on agent exit.

Permission model

Mode Behavior
ask Every tool use requires human confirmation
bubble Permission prompts float up to team lead
allow Auto-approve, bounded by lead's permissions

Known bug: If the lead agent is in Delegate Mode, all spawned teammates inherit the restriction and lose file operation tools (Bash, Read, Write, Edit, Grep, Glob) even when mode: "bypassPermissions" is set.

What depends on it

Trade-offs and limitations

36.8 GB lesson: TEAMMATE_MESSAGES_UI_CAP = 50 was added after an internal test with 292 agents consumed 36.8 GB of memory. Every engineering limit has a story.

50-message UI cap: Prevents unbounded message queue growth during large swarms.

No recursive forking: Anti-recursion enforced by <fork_boilerplate_tag> marker — fork children see AgentTool but reject attempts to fork recursively.

Lead context doesn't carry over: Spawned teammates are peers, not children. They load the same project context (CLAUDE.md, MCP, skills) but not the lead's conversation history.

omitClaudeMd optimization: Read-only agents (explore, plan) are spawned with omitClaudeMd: true, saving 5-15 GTok/week across Anthropic's fleet.

Key claims

Relationships

Evidence

Open questions