TeammateTool

The multi-agent coordination layer in claude-code. Not a single spawn function — it exposes 13 distinct operations covering the full team lifecycle, from creation through task claiming to graceful shutdown.

13 Operations

Team Setup

• spawnTeam — creates team folder structure at ~/.claude/teams/{name}/
• discoverTeams — list available/joinable teams
• cleanup — remove team resources when done

Membership

• requestJoin — request to join an existing team
• approveJoin — lead agent approves a join request
• rejectJoin — lead rejects

Task Coordination

• TaskCreate — add task with blockedBy dependency declarations
• TaskClaim — atomic task claiming (file-lock protected against race conditions)
• TaskComplete — mark done, auto-unblocks dependent tasks

Communication

• SendMessage — direct message to one named teammate
• Broadcast — message to all teammates (use sparingly — cost scales with team size)
• requestShutdown — initiate graceful shutdown
• approveShutdown — teammate acknowledges shutdown signal

Three Execution Models

Additional isolation modes: git worktree (own branch and directory), DreamTask (background memory consolidation), MonitorMcpTask (MCP server monitoring).

Task Claiming and Locking

The task list is a shared work queue stored as JSON files in ~/.claude/tasks/{team-name}/. Claiming uses file locking: writing to current_tasks/parse_if_statement.txt prevents others from claiming the same work. Lock retries: 30 attempts at 5-100ms backoff (~2.6 second max wait).

Tasks have three states: pending, in-progress, completed. When a task moves to completed, any tasks listing it in blockedBy are automatically unblocked.

Critical: the locking applies to task claiming, not to 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

Each teammate has an independent async message queue stored as JSON: ~/.claude/teams/{name}/inboxes/{agent}.json. Structured message types include shutdown_request, plan_approval_response, and permission bubbling (teammates can escalate permission requests up to the lead).

The 36.8 GB Lesson

TEAMMATE_MESSAGES_UI_CAP = 50 was not added speculatively — it was added after an internal test run with 292 agents triggered a memory leak consuming 36.8 GB. Every concrete engineering limit in the codebase has a production failure story behind it.

Permission Modes

• ask — every tool use requires human confirmation
• bubble — permission prompts float up to the team lead
• allow — auto-approve, bounded by the lead's own permissions

Known bug: if the lead agent is in Delegate Mode, all spawned teammates inherit the restriction and lose file operation tools, even when mode: "bypassPermissions" is set.

Git Worktree Isolation

When isolation: worktree is set, Claude Code creates a temporary git worktree with its own working directory, staging area, and HEAD — but sharing .git/objects/ (history stored once). Five simultaneous worktree agents produce five independent branches that merge through standard PRs. Cleanup is automatic on exit.

Feature Gate

Process-based agents gated behind tengu_amber_flint. Each agent receives a color assignment and identity flags (--agent-name, --team-name).

Key Claims

• clm-20260409-70ae73ca3197: 13 operations for full team lifecycle
• clm-20260409-cb5c35c8f998: UI cap added after 292-agent / 36.8 GB incident

Sources

• src-20260409-a14e9e98c3cd — Internals: Auto-Memory, Auto-Dream, and Agent Teams