Coordinates Claude agent teams via filesystem protocol. Use when orchestrating parallel agents with task dependencies. Do not use for single-agent tasks.
Coordinates Claude agent teams via filesystem protocol. Use when orchestrating parallel agents with task dependencies. Do not use for single-agent tasks.
Claude Code Agent Teams enables multiple Claude CLI processes to collaborate on shared work through a filesystem-based coordination protocol. Each teammate runs as an independent claude process in a tmux pane, communicating via JSON files guarded by fcntl locks, with no database, daemon, or network layer.
This skill provides the patterns for orchestrating agent teams effectively.
When To Use
Parallel implementation across multiple files or modules
Multi-agent code review (one agent reviews, another implements fixes)
Large refactoring requiring coordinated changes across subsystems
Tasks with natural parallelism that benefit from concurrent agents
When NOT To Use
Single-file changes or small tasks (overhead exceeds benefit)
See modules/spawning-patterns.md for tmux pane management and color assignment.
3. Create Tasks with Dependencies
{"id":"1","subject":"Implement API endpoints","description":"Create REST endpoints for user management","status":"pending","owner":null,"blocks":["3"],"blocked_by":[],"metadata":{}}
See modules/task-coordination.md for state machine and dependency management.
4. Coordinate via Messages
{"from":"team-lead","text":"API endpoints are ready for integration testing","timestamp":"2026-02-07T22:00:00Z","read":false,"summary":"API ready"}
See modules/messaging-protocol.md for message types and inbox operations.
Coordination Workflow
agent-teams:team-created: Initialize team config and directories
agent-teams:teammates-spawned: Launch agents in tmux panes
agent-teams:tasks-assigned: Create tasks with dependencies, assign owners
agent-teams:coordination-active: Agents claim tasks, exchange messages, mark completion
agent-teams:team-shutdown: Graceful shutdown with approval protocol
Crew Roles
Each team member has a role that determines their capabilities and task
compatibility. Five roles are defined: implementer (default), researcher,
tester, reviewer, and architect. Roles constrain which risk tiers an
agent can handle. See modules/crew-roles.md for the full capability matrix
and role-risk compatibility table.
Team Formation
For mission-level team sizing, use the Team Formation rules
from references/team-formation.md. This defines:
Maximum team size: 10 agents (coordination overhead limit)
File ownership rules: Prevent conflicts with clear ownership
See references/team-formation.md for full team sizing
guidance and example team formations.
Health Monitoring
Team members can be monitored for health via heartbeat messages and claim expiry. The lead polls team health every 60s with a 2-stage stall detection protocol (health_check probe and 30s wait). Stalled agents have their tasks released and are restarted or replaced following the "replace don't wait" doctrine. See modules/health-monitoring.md for the full protocol and state machine.
Module Reference
team-management.md: Team lifecycle, config format, member management
Use Skill(conjure:delegation-core) first to determine if the task benefits from multi-agent coordination vs. single-service delegation.
Worktree Isolation Alternative (Claude Code 2.1.49+)
For parallel agents that modify files, isolation: worktree provides a lightweight alternative to filesystem-based coordination. Each agent runs in its own temporary git worktree, eliminating the need for fcntl locking or inbox-based conflict avoidance on shared files.
When to prefer worktrees over agent teams messaging: Agents work on overlapping files but don't need mid-execution communication
When to prefer agent teams messaging: Agents need to coordinate discoveries or adjust plans based on each other's progress
Combine both: Use agent teams for coordination with isolation: worktree per teammate for filesystem safety
Troubleshooting
Common Issues
tmux not found
Install via package manager: brew install tmux / apt install tmux
Stale lock files
If an agent crashes mid-operation, lock files may persist. Remove .lock files manually from ~/.claude/teams/<team>/inboxes/ or ~/.claude/tasks/<team>/
Orphaned tasks
Tasks claimed by a crashed agent stay in_progress indefinitely. Use modules/health-monitoring.md for heartbeat-based stall detection and automatic task release. The health monitoring protocol detects unresponsive agents within 60s and 30s probe window and releases their tasks for reassignment.
Message ordering
Filesystem timestamp resolution varies (HFS+ = 1s granularity). Use numbered filenames or UUID-sorted names to avoid collision on rapid message bursts.
Model errors on Bedrock/Vertex/Foundry (pre-2.1.39)
Teammate agents could use incorrect model identifiers on enterprise providers, causing 400 errors. Upgrade to Claude Code 2.1.39+ for correct model ID qualification across all providers.
Nested session guard (2.1.39+)
If claude refuses to launch within an existing session, ensure you're using
tmux pane splitting (not subshell invocation). The guard is intentional. See
modules/spawning-patterns.md for details.
