| name | claude-teams |
| description | Guide for coordinating multiple Claude Code agents as teams. Use when setting up agent teams, configuring subagents, orchestrating multi-agent workflows, or building programmatic agent systems with the Claude Agent SDK. |
| license | MIT |
Claude Teams
Coordinate multiple Claude Code agents working together on shared tasks.
When forming a team
Invoke /core:agent-loop for the 4-phase / 6-tier execution model.
Invoke /claude-code:claude-agents for agent file format, tool allowlists, and model selection.
Invoke /core:anti-fabrication always — every claim about a tool, file, or test result requires tool execution.
Require each teammate to quote one sentence from each loaded skill in its first message as proof of loading. Do not proceed with the teammate's work until proof is received.
Glob patterns like /core:* do not expand in Agent prompts. List skill names explicitly.
When to Use
Activate when:
- Setting up or configuring Agent Teams (experimental)
- Creating custom subagents for task delegation
- Building multi-agent workflows with the Claude Agent SDK
- Designing coordination patterns for parallel agent work
- Troubleshooting agent communication or task assignment
Approaches
Three approaches exist for multi-agent coordination, each with different trade-offs:
| Approach | Communication | Coordination | Best For |
|---|
| Agent Teams | Peer-to-peer messaging + shared task list | Team lead + self-coordination | Collaborative work requiring discussion |
| Subagents | Report back to parent only | Parent manages all | Focused delegated tasks |
| Agent SDK | Programmatic message streaming | Developer-controlled | CI/CD, automation, custom apps |
Agent Teams (Experimental)
First-party multi-agent coordination. A team lead spawns teammates that work independently with peer-to-peer messaging and a shared task list.
Enable with: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
For setup, configuration, and usage details, see references/agent-teams.md.
Subagents (Task Tool)
Lightweight delegation within a single session. Subagents run in their own context window, complete a task, and return results to the parent.
For subagent types, custom agents, and isolation patterns, see references/subagents.md.
Agent SDK
Programmatic multi-agent orchestration in Python and TypeScript using the same tools that power Claude Code.
For SDK setup, agent definitions, and session management, see references/agent-sdk.md.
Multi-Agent Patterns
Proven patterns for file ownership, task decomposition, scaling, and quality gates.
For architecture guidance and case studies, see references/patterns.md.
Orchestration primitives
/core:agent-loop defines the decomposition + delegation flow. Four Claude Code primitives compose with it for long-running or recurring work:
| Primitive | Use when |
|---|
/loop <prompt> | You want a self-pacing tick: monitor agents, poll the tracker, advance the queue. Auto-paces via ScheduleWakeup. |
| Routines | Cron-style scheduled remote agents. Use for daily/weekly autonomous runs. |
| Channels | Event-driven (webhook/integration) entry points. Use when an external system kicks the loop. |
| Workflows | Fan-out exceeds one turn, the orchestration itself must be repeatable, or results need independent verification passes — see /claude-code:claude-workflows. |
Workflows require explicit opt-in and run in the background; /core:agent-loop "Optional: workflow execution substrate" defines how the five-tier pipeline maps onto them.
/loop example — shepherd a running epic
After dispatching a team for an epic, the operator session runs:
/loop /shepherd
where /shepherd is a project-defined command (not shipped with this plugin — define it in your project's .claude/commands/) that, each tick:
- Reads bees/tracker state for the epic's issues
- Promotes ready issues to in_progress
- Notifies the operator if any agent transitioned to a review or needs_help state
- Halts and pings via PushNotification when the cohort is complete
The /loop harness auto-paces via ScheduleWakeup (default 270s — stays inside the prompt-cache TTL). The operator session is hands-off until the loop fires a notification.
This is the recommended composition for long-running multi-agent work: /core:agent-loop does the per-spawn discipline; /loop does the queue advancement.
