Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What 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 in src/config/redis.ts, Task 3: tests in tests/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-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill agent-teams -a claude-code

3Manually: put the files in place

~/.claude/skills/agent-teams/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-teams/

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.

agent-teams alinaqi agent-teams coordinates AI agents around a required TDD pipeline. Use it when feature work needs ordered checks, security review, and pull request creation. CX Codex +1 300installs agent-teams travisjneuman Teaches Claude how to compose agent teams: which tasks split well, how many teammates to spawn, and what goes into each spawn prompt. Active only once teams are enabled. CX Codex +1 153installs suede-agent-teams JasonColapietro suede-agent-teams splits development tasks across multiple AI agents with Git collision detection, exclusive file lanes, and structured ledger reporting. CX Codex +1 ★ 121repo stars Microsoft Teams Automation Claude Office Skills Microsoft Teams Automation — a skill that drives Microsoft Teams from an AI agent: channel messages, meeting scheduling, webhooks and bot workflows. CX Codex +1 4,900installs openhuddle nika110 openhuddle connects teammate coding agents into a multiplayer workflow with a shared task board, file claims, and collaborative design discussions. CX Codex +1 ★ 6repo stars team-coordination alinaqi team-coordination coordinates multiple Claude Code sessions in a single repository via shared Markdown state files and task claiming. Helps developer teams avoid merge conflicts when editing the same codebase. CX Codex +1 321installs agenthub Alireza Rezvani agenthub spawns parallel subagents in isolated git worktrees to compete on tasks, compares outcomes with metric checks or an LLM judge, and merges the winner. ★ 30,251repo stars agents-crewai Orchestra Research agents-crewai — a Claude skill for assembling teams of autonomous agents with roles, memory, and sequential or hierarchical task execution. CX Codex +1 371installs

From the same set83

The whole set →
insights insights turns your pro-workflow history into numbers: edits per session, rules you actually apply, mistakes that keep coming back. Useful when you want to see where the agent keeps slipping. CX Codex +1 ★ 2,966repo stars doctor doctor scans your pro-workflow and Claude Code setup: checks hooks, database, context usage, MCP servers, and git state. Spots broken hook scripts and settings conflicts before they cause problems. CX Codex +1 ★ 2,966repo stars thoroughness-scoring thoroughness-scoring rates implementation choices from 1 to 10 and prompts the agent to pick thorough solutions with tests and typing over brittle shortcuts. CX Codex +1 ★ 2,966repo stars skill-optimizer The skill-optimizer skill proposes edits to a SKILL.md based on stored corrections, then checks candidates against held-out examples before accepting changes. CX Codex +1 ★ 2,966repo stars sprint-status sprint-status tracks parallel Claude Code sessions and prevents confusion by enforcing session headers and standardized status lines. CX Codex +1 ★ 2,966repo stars skill-router The skill-router skill maps pro-workflow skills and commands to jobs, with guidance on when to use each and whether a person or the agent starts it. Use it when you’re unsure what fits. CX Codex +1 ★ 2,966repo stars permission-analyst permission-analyst analyzes permission prompts and auto mode denials, recommends permissions rules and autoMode entries. Use it when prompts slow you down or auto mode keeps falling back to confirmations. CX Codex ★ 2,966repo stars safe-mode safe-mode intercepts destructive terminal commands and confines agent edits to a specific directory using Claude Code hooks. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open