From majestic-tools
Coordinates multiple Claude Code instances as agent teams for workflows needing inter-agent communication. Covers TeamCreate, SendMessage types, task coordination, hooks, and orchestration patterns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/majestic-tools:agent-teamsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Coordinate multiple Claude Code instances as a team with shared task lists, inter-agent messaging, and independent context windows. Fundamentally different from subagents (Task tool): teammates communicate directly with each other, not just back to the caller.
Coordinate multiple Claude Code instances as a team with shared task lists, inter-agent messaging, and independent context windows. Fundamentally different from subagents (Task tool): teammates communicate directly with each other, not just back to the caller.
Does the work require inter-agent communication?
├── No → Use subagents (Task tool)
│ ├── Focused tasks where only the result matters
│ ├── Research/verification that reports back
│ └── Lower token cost (results summarized to main context)
└── Yes → Use Agent Teams
├── Teammates need to share findings mid-task
├── Adversarial debate / competing hypotheses
├── Self-organizing work from shared task list
└── Complex coordination across 3+ parallel workers
How many parallel workers?
├── 1-3 independent tasks → Subagents (less overhead)
├── 3-5 coordinating workers → Agent Teams
└── 5+ workers → Agent Teams with delegate mode
Best use cases:
Avoid when:
Enable Agent Teams (experimental, disabled by default):
// settings.json (user or project level)
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Or set in shell: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Agent Teams use four distinct tools (not a single "TeammateTool"):
| Tool | Purpose |
|---|---|
| TeamCreate | Creates team config + task directory. Caller becomes lead |
| SendMessage | All inter-agent communication (5 message types below) |
| TeamDelete | Removes team resources after shutdown (cleanup) |
| Task (extended) | Spawns teammates when name + team_name params present |
| Type | Parameters | Description |
|---|---|---|
message | recipient, content, summary | Direct message to one teammate |
broadcast | content, summary | Message to all teammates (expensive — N deliveries) |
shutdown_request | recipient, content | Request teammate termination (lead only) |
shutdown_response | request_id, approve, content | Accept/reject shutdown (teammate only) |
plan_approval_response | request_id, approve, recipient, content | Approve/reject plan (lead only) |
Critical: Plain text output is NOT visible to teammates. Agents MUST use SendMessage for all inter-agent communication.
Usage notes:
message over broadcast — broadcast creates N messages for N teammatesMethod 1: Natural language — Tell Claude to create a team and describe structure:
Create an agent team to review this PR. Spawn three reviewers:
- One focused on security
- One checking performance
- One validating test coverage
Method 2: Task tool with team parameters:
Task({
team_name: "my-team",
name: "worker-1",
subagent_type: "general-purpose",
prompt: "Review src/auth/ for security vulnerabilities...",
model: "sonnet",
run_in_background: true
})
Teammate receives on spawn:
Built-in agent types for teammates:
| Type | Capabilities |
|---|---|
general-purpose | All tools (Edit, Write, Bash, Task, etc.) |
Explore | Read-only — codebase search and analysis |
Plan | Read-only — architectural design |
Bash | System commands only |
Model selection: Use Sonnet for most teammates (cost-effective). Reserve Opus for leads or complex reasoning tasks. Specify via model parameter or natural language ("Use Sonnet for each teammate").
Controls how teammates display. Set via teammateMode in settings.json or --teammate-mode CLI flag.
| Mode | Setting | Requirements | Behavior |
|---|---|---|---|
| Auto (default) | "auto" | None | Split panes if in tmux, else in-process |
| In-process | "in-process" | None | All in main terminal. Shift+Up/Down to select |
| Split panes | "tmux" | tmux or iTerm2 | Each teammate gets own pane |
// settings.json
{ "teammateMode": "in-process" }
# CLI override for single session
claude --teammate-mode in-process
Auto-detection logic:
$TMUX env var set → use tmux split panes$ITERM_SESSION_ID set + it2 available → use iTerm2which tmux succeeds → use tmuxIn-process navigation:
Split-pane navigation:
Direct message (type: "message"): Send to one specific teammate via SendMessage. Use for targeted instructions, follow-ups, or redirecting approach.
Broadcast (type: "broadcast"): Send to all teammates simultaneously via SendMessage. Use sparingly — costs scale with team size. Good for: announcing shared decisions, requesting status updates.
Automatic delivery: Messages arrive at recipients automatically. Lead does not need to poll for updates.
Idle notifications: When a teammate finishes and stops, it automatically notifies the lead.
Message type schemas: See assets/message-formats.yml
The shared task list coordinates work across the team. All agents see task status and can claim available work.
Task lifecycle: pending → in_progress → completed
Assignment patterns:
Dependencies:
blockedBy field (array of task IDs)File locking: Task claiming uses file locking to prevent race conditions when multiple teammates try to claim simultaneously.
Recommended task sizing:
Restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. Prevents lead from implementing tasks itself.
Enable: Press Shift+Tab to cycle into delegate mode after starting a team.
When to use:
Known bug: Teammates spawned AFTER entering delegate mode inherit restricted tool access (lose Read, Write, Edit, Bash, Glob, Grep). Workaround: Spawn all teammates BEFORE pressing Shift+Tab.
When to skip:
Require teammates to plan before implementing. Teammate works in read-only plan mode until lead approves.
Spawn with plan approval:
Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.
The planModeRequired field in team config controls this per-member.
Workflow:
1. Teammate spawned with planModeRequired: true
2. Teammate explores codebase, creates plan
3. Teammate sends plan_approval_request to lead
4. Lead reviews plan:
├── approvePlan → teammate exits plan mode, begins implementation
└── rejectPlan(feedback) → teammate stays in plan mode, revises
5. Cycle repeats until approved
Influence approval criteria via prompt:
Only approve plans that include test coverage.
Reject plans that modify the database schema.
Two teammates editing the same file causes overwrites. Prevent this by assigning file ownership:
- teammate-1: owns src/api/ files
- teammate-2: owns src/ui/ files
- teammate-3: owns tests/ files
Anti-pattern: Multiple teammates modifying shared config files, package.json, or migration files simultaneously.
Mitigation: Use task dependencies to serialize edits to shared files.
Two hook events for enforcing quality gates in agent teams:
Fires when a teammate is about to go idle after finishing its turn.
teammate_name, team_nameFires when a task is being marked as completed (via TaskUpdate or when teammate finishes with in-progress tasks).
task_id, task_subject, task_description, teammate_name, team_nameTeammateIdle: command hooks only (no prompt/agent hooks). TaskCompleted: supports command, prompt, and agent handler types.
See assets/hook-examples.yml for configuration examples.
Shutdown sequence:
1. Lead sends requestShutdown to each teammate
2. Teammate receives request:
├── approveShutdown → finishes current request/tool call, terminates
└── rejectShutdown(reason) → continues working
3. Wait for all teammates to terminate
4. Lead calls cleanup
├── If active teammates remain → cleanup fails
└── If all terminated → removes team config + task directories
Important:
tmux ls && tmux kill-session -t <name>--dangerously-skip-permissions, all teammates do too~/.claude/
├── teams/
│ └── {team-name}/
│ ├── config.json # team config (members, lead, settings)
│ └── inboxes/
│ └── {agent}.json # per-agent message inbox
└── tasks/
└── {team-name}/
├── 1.json # task files (auto-incremented IDs)
├── 2.json
└── N.json
See assets/team-config-schema.yml for full schemas.
| Limitation | Impact | Workaround |
|---|---|---|
| No session resumption with in-process teammates | /resume and /rewind don't restore teammates | Tell lead to spawn new teammates after resume |
| Task status can lag | Teammates sometimes fail to mark tasks completed | Manually update or tell lead to nudge teammate |
| Shutdown can be slow | Teammates finish current request before stopping | Wait patiently or spawn replacement |
| One team per session | Cannot manage multiple teams from one lead | Clean up current team before starting new one |
| No nested teams | Teammates cannot spawn their own teams | Only leads manage team structure |
| Lead is fixed | Cannot promote teammate or transfer leadership | Plan team structure before starting |
| Permissions set at spawn | All teammates inherit lead's permission mode | Change individual modes after spawning |
| Split panes require tmux/iTerm2 | Not supported in VS Code terminal, Windows Terminal, Ghostty | Use in-process mode as fallback |
| 5-minute heartbeat timeout | Inactive teammates auto-marked inactive | Keep teammates active with tasks |
| Broadcast scales linearly | N messages for N teammates | Prefer targeted message over broadcast |
| Delegate mode spawn bug | Teammates spawned after Shift+Tab lose file tools | Spawn all teammates before entering delegate mode |
| Error | Cause | Fix |
|---|---|---|
| "Cannot cleanup with active members" | Teammates still running | requestShutdown all teammates first |
| "Already leading a team" | Team already exists | cleanup existing team or use different name |
| "Agent not found" | Wrong teammate name/ID | Check config.json for correct agent IDs |
| "Team does not exist" | No team created | Run spawnTeam first |
| Teammates not appearing | Various | Shift+Down to cycle; check task complexity; verify tmux installed |
| Too many permission prompts | Teammate permissions bubble to lead | Pre-approve common operations in settings |
| Lead shuts down before work done | Lead thinks team is finished | Tell lead to wait for teammates |
See references/orchestration-patterns.md for 4 detailed patterns:
npx claudepluginhub majesticlabs-dev/majestic-marketplace --plugin majestic-toolsOrchestrates Claude Code agent teams for parallel multi-agent workflows on complex tasks using TeamCreate, SendMessage, TaskUpdate, and shared task lists. Enable with --enable-teams flag.
Orchestrates Claude Code agent teams: spawn teammates, assign tasks with dependencies, manage communication via messages or broadcasts, configure modes, and set quality gate hooks.
Orchestrates teams of Claude Code sessions for parallel work on research, features, debugging, and cross-layer tasks using shared tasks, inter-agent messaging, and team lead coordination.