agent-teams · rohitg00 — Claude Code skill: run agents as a team
agent-teams is a Claude Code skill that coordinates multiple sessions through shared tasks, messaging, and file locks. Teammates work in parallel on separate parts of the codebase.
MIT ★ 2,966 updated 2026-09-29
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflowWhat agent-teams does
agent-teams turns separate Claude Code sessions into a single working group. The first session becomes the lead, others join as teammates. They coordinate through a shared mailbox, tackle different tasks in parallel, and claim files to avoid merge conflicts. Teammates are full Claude Code sessions—each with its own context window and access to all tools, not lightweight subordinates reporting back to a parent.
Work breaks into units that touch different files and can be tested independently. The lead reviews plans before implementation, teammates grab unblocked tasks, and dependencies flow automatically. A team of 3–5 hits the sweet spot: enough parallelism without drowning the lead in coordination. Teams larger than 5 spend more time coordinating than they gain in speed.
Enable it with the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, then run claude. Cycle through teammates with Shift+Down or open each in its own tmux window. The lead can switch to delegate mode (Shift+Tab) to coordinate only, leaving all coding to teammates.
What it helps with
- split a large project across multiple AI sessions without file conflicts
- work on API, UI, and tests in parallel without stepping on each other
- prevent teammates from depending on each other in the wrong order
- review plans before implementation to avoid rework
Example prompts for the agent
- Start the lead:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 && claude, then open teammates in other terminals within the same repo - Break the work down: "Task 1: add rate-limit middleware in
src/middleware/rate-limit.ts, Task 2: Redis config insrc/config/redis.ts, Task 3: tests intests/rate-limit.test.ts" - Cycle between sessions with Shift+Down to see each teammate's task, review and approve plans before they build
How to install agent-teams
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflowThis installs the whole pro-workflow plugin with all its skills
2Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill agent-teams -a claude-code3Manually: put the files in place
~/.claude/skills/agent-teams/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agent-teams/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill agent-teams -a codex2Manually: put the files in place
.agents/skills/agent-teams/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill agent-teams -a cursor2Manually: put the files in place
.cursor/skills/agent-teams/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rohitg00/pro-workflow skills/agent-teams2Manually: put the files in place
.github/skills/agent-teams/SKILL.md1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill agent-teams -a gemini-cli2Platform CLI
gemini skills install https://github.com/rohitg00/pro-workflow --path skills/agent-teamsManually: put the files in place
.devin/skills/agent-teams/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about agent-teams
How do I install agent-teams in Claude Code?
Run /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow, then npx skills add rohitg00/pro-workflow --skill agent-teams -a claude-code. Alternatively, open ~/.claude/skills/agent-teams/SKILL.md.
How is agent-teams different from subagents?
Teammates are full Claude Code sessions with their own context and all tools available; they talk to each other directly. Subagents are lightweight and report only to the parent. Teams work best for parallel coding; subagents for quick background tasks.
How many teammates should a team have?
3–5 is ideal: enough parallelism without drowning the lead in handoffs. Beyond 5, coordination overhead outweighs the speed gain. Aim for 5–6 tasks per teammate to balance utilization and focus.
Source text
SKILL.md · MIT
---
name: agent-teams
description: Coordinate multiple Claude Code sessions as a team — lead + teammates with shared task lists, mailbox messaging, and file-lock claiming. Patterns for team sizing, task decomposition, and when to use teams vs sub-agents vs worktrees.
user-invocable: true
---
# Agent Teams
Coordinate multiple Claude Code sessions working on the same codebase simultaneously.
## Enable
```bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude # starts as team lead
```
The first session becomes the team lead. Subsequent sessions in the same repo join as teammates.
## Architecture
```text
Team Lead (coordinates, delegates, reviews)
├── Teammate 1 (owns task A, messages lead + peers)
├── Teammate 2 (owns task B, messages lead + peers)
└── Teammate 3 (owns task C, messages lead + peers)
│
└── Shared: task list + mailbox + file locks
```
**Key difference from subagents:** Teammates are full Claude Code sessions. They have their own context window, can use all tools, and message each other directly — not just report back to a parent.
## Team Sizing
| Team Size | Best For |
|-----------|----------|
| 2 | One builds, one reviews |
| 3-5 | Parallel features across layers (API, UI, tests) |
| > 5 | Coordination overhead outweighs parallelism |
3-5 teammates is the productive range. Beyond that, the lead spends more time coordinating than the team saves.
**Task granularity:** Aim for 5-6 tasks per teammate. Fewer means underutilization; more means excessive context switching.
## Display Modes
**In-process navigation:**
- `Shift+Down` — cycle through teammates (wraps around)
- See each teammate's current task and output
**Split-pane (recommended for >2 teammates):**
- tmux: `tmux split-window -h` per teammate
- iTerm2: Cmd+D for vertical split
- Each pane runs its own `claude` session
## Task Management
Tasks flow through states:
```text
pending → in-progress → completed
│
└── blocked (waiting on dependency)
```
### Task Decomposition
Break work into units that:
- Touch non-overlapping files
- Can be verified independently
- Have clear done criteria
**Good decomposition:**
```text
Task 1: Add rate limiting middleware (src/middleware/rate-limit.ts)
Task 2: Add rate limit tests (tests/rate-limit.test.ts)
Task 3: Update API docs for rate limit headers (docs/api.md)
Task 4: Add Redis config for rate limit store (src/config/redis.ts)
```
**Bad decomposition:**
```text
Task 1: Implement rate limiting
Task 2: Fix rate limiting bugs
Task 3: Improve rate limiting
```
### Dependencies
Tasks can declare dependencies:
```text
Task 3 (API docs) → depends on Task 1 (middleware)
Task 2 (tests) → depends on Task 1 (middleware)
Task 4 (Redis config) → no dependencies
```
Teammates pick up unblocked tasks automatically.
## File-Lock Claiming
Teammates claim files before editing to prevent conflicts:
1. Teammate checks if file is locked
2. If free, claims it (file-lock-based)
3. Edits the file
4. Releases lock on task completion
If two teammates need the same file, one waits or the lead reassigns.
## Plan Approval
Teammates plan before implementing:
1. Teammate receives task
2. Writes a brief plan (files to change, approach)
3. Lead reviews plan
4. Lead approves or redirects
5. Teammate implements
This prevents wasted work from misunderstood requirements.
## Delegate Mode
`Shift+Tab` toggles delegate mode for the lead:
- Lead coordinates only — no direct code edits
- All implementation delegated to teammates
- Lead reviews, approves plans, manages task flow
## Hook Events
| Hook | Fires When |
|------|------------|
| TeammateIdle | A teammate finishes its task and has no pending work |
| TaskCreated | New task added to the shared list |
| TaskCompleted | A teammate marks a task done |
Use these to trigger notifications, auto-assign next tasks, or run integration tests when all tasks complete.
## When to Use Teams vs Alternatives
| Scenario | Use |
|----------|-----|
| Parallel work on non-overlapping files | Agent teams |
| Quick background exploration | Subagent |
| Isolated feature branch work | Worktree (`claude -w`) |
| Competing approaches to same problem | Worktrees (compare results) |
| Cross-layer changes (API + UI + tests) | Agent teams |
| One-off delegation | Subagent with `isolation: worktree` |
| Large-scale migration (20+ files) | `/batch` command |
## Anti-Patterns
- More than 5 teammates — coordination overhead dominates
- Tasks that share mutable state or the same files
- Skipping plan approval — leads to rework
- Lead doing implementation instead of coordinating (use delegate mode)
- Not setting dependencies — teammates race on coupled tasks
## Example Session
```text
Lead: "We need rate limiting. Breaking into 4 tasks."
Task 1: middleware implementation → Teammate 1
Task 2: Redis config → Teammate 2 (no deps)
Task 3: tests → Teammate 1 (after Task 1)
Task 4: API docs → Teammate 2 (after Task 1)
Teammate 1 plans → Lead approves → implements Task 1
Teammate 2 plans → Lead approves → implements Task 2
Task 1 completes → unblocks Tasks 3 and 4
Teammate 1 picks up Task 3, Teammate 2 picks up Task 4
All complete → Lead runs integration tests → commits
```
## Docs
https://code.claude.com/docs/agent-teams
© Rohit Ghumare · MIT · rohitg00/pro-workflow
Similar skills
All skills for Agent setup: memory, context, orchestration →agent-teams by other authors comes first.