Claude Code Agent Teams

Set up and run parallel Claude Code sessions with a project-local workflow harness. One command.

npx claude-agent-teams init

Agent teams are experimental. Docs

Requires Claude Code v2.1.32+.

Install

Option 1: npx (no install)

npx claude-agent-teams <command>

Option 2: global install

npm i -g claude-agent-teams
claude-agent-teams <command>

Requires Node 16+ (you already have it if you use Claude Code).

Commands

init

Set up agent teams in your project. Installs a root CLAUDE.md, scaffolds a local .claude-agent-teams/ harness, enables the feature flag, and configures your display mode. Walks you through everything.

npx claude-agent-teams init
npx claude-agent-teams init ./my-project

Skip the prompts with flags:

npx claude-agent-teams init -y                                    # defaults, no prompts
npx claude-agent-teams init --template=fullstack --mode=tmux      # one-liner
npx claude-agent-teams init --harness=delivery                    # feature-delivery pack
npx claude-agent-teams init --template=monorepo --no-settings     # skip settings
npx claude-agent-teams init --template=base --force               # overwrite existing

| Flag | Values | Default | |:---|:---|:---| | --template | base, monorepo, fullstack, skip | base | | --harness | starter, delivery, investigation, all, skip | starter | | --mode | auto, in-process, tmux | auto | | --no-settings | — | writes to settings | | --force | — | skips if exists | | -y, --yes | — | interactive |

list

Browse all 30+ templates with descriptions. Every template tells you what it does and when to use it — no need to leave your terminal.

npx claude-agent-teams list                  # everything
npx claude-agent-teams list prompts          # just scenario prompts
npx claude-agent-teams list spawn-prompts    # just role templates
npx claude-agent-teams list coordination     # just coordination patterns

info

Preview any template before adding it — see what it contains, what sections it covers, and how to use it.

npx claude-agent-teams info prompts/quickstart
npx claude-agent-teams info spawn-prompts/architect
npx claude-agent-teams info coordination/contract-first

add

Copy a template into your project. Shows contextual next steps after copying — different guidance for prompts, roles, CLAUDE.md, and coordination patterns.

npx claude-agent-teams add prompts/quickstart           # your first team
npx claude-agent-teams add prompts/code-review          # parallel PR review
npx claude-agent-teams add claude-md/fullstack ./app    # CLAUDE.md for fullstack
npx claude-agent-teams add spawn-prompts/architect      # role template

validate

Check your project is configured correctly — Claude Code version, feature flag, CLAUDE.md, local harness, unfilled placeholders, file ownership rules, tmux.

npx claude-agent-teams validate
npx claude-agent-teams validate ./my-project

Every command supports --help:

npx claude-agent-teams init --help
npx claude-agent-teams list --help
npx claude-agent-teams add --help
npx claude-agent-teams info --help

Workflow

npx claude-agent-teams init                         # 1. set up your project
vim CLAUDE.md                                      # 2. fill in {{ placeholders }}
npx claude-agent-teams validate                    # 3. check version, settings, and harness
claude                                             # 4. start Claude Code
# 5. paste a prompt from .claude-agent-teams/prompts/

What init installs

By default, init creates a local .claude-agent-teams/ directory with a curated workflow pack.

• starter — first teams, launch, recovery, and quality gates
• delivery — feature shipping, contracts, review, and verification
• investigation — debugging, research, and competing hypotheses
• all — install every curated pack

What's inside

Scenario Prompts — templates/prompts/

Copy-paste these into Claude Code to spin up a team. Each one defines roles, tasks, and file ownership.

| Template | Use case | |:---|:---| | Quickstart | Your first team — minimal, 2 teammates, learn the basics | | Code Review | Parallel PR review — security, performance, test lenses | | Debugging | Competing hypotheses — multiple theories in parallel | | Feature Development | Parallel module building with plan approval | | Refactoring | Parallel module refactoring — shared interface, independent internals | | Research & Exploration | Multi-angle design exploration — breadth before depth | | Cross-Layer | Frontend + backend + DB + tests — one teammate per layer | | Migration | Framework/language migration — each module independently | | Test Suite | Parallel test writing — one teammate per module | | Documentation | Parallel docs — API ref, user guide, contributor guide |

CLAUDE.md Templates — templates/claude-md/

Every teammate auto-reads CLAUDE.md from your project root. This is where file ownership, code standards, and team conventions live. init installs one for you.

| Template | For | |:---|:---| | Base | Any project | | Monorepo | Multi-package workspaces (Nx, Yarn Workspaces, Lerna) | | Fullstack | Frontend / backend / database layers |

Spawn Prompts — templates/spawn-prompts/

Teammates don't inherit conversation history. These give each role full context from the start — paste them when spawning a teammate.

| Role | Responsibility | |:---|:---| | Architect | Design systems, define interfaces, review plans | | Implementer | Build code — frontend, backend, or fullstack | | Tester | Write tests, validate coverage, find edge cases | | Reviewer | Review through a lens — security, performance, a11y | | Researcher | Investigate options, evaluate tradeoffs | | Devil's Advocate | Challenge assumptions, find failure modes |

Task Breakdowns — templates/task-breakdowns/

5–6 tasks per teammate is the sweet spot.

| Template | Work type | |:---|:---| | Feature | New feature with dependency chains across 3-4 teammates | | Refactor | Foundation → modules → verification sequence | | Investigation | Hypothesis-driven debugging with parallel investigation |

Coordination Patterns — templates/coordination/

How teammates hand off work and stay in sync.

| Pattern | Flow | |:---|:---| | Contract-First | Define interfaces → approve → implement in parallel → verify | | Pipeline | Sequential stages with parallel work within each | | Peer Review | Implement in parallel → cross-review → fix → merge |

Guides

Decision frameworks, lifecycle management, quality gates, and common pitfalls.

| Guide | Covers | |:---|:---| | When to Use Teams | Single session vs. subagents vs. agent teams — decision flowchart | | Team Lifecycle | Create → monitor → steer → shutdown → cleanup | | Sizing & Cost | Team size, model selection, token budgets | | Anti-Patterns | 10 common mistakes and how to fix them | | Troubleshooting | Teammates not appearing, stale tasks, orphaned sessions | | Quality Gates | TeammateIdle, TaskCompleted, and verification gates | | Resume & Recovery | Recover resumed sessions, stale tasks, and missing teammates |

Config Reference

| File | Covers | |:---|:---| | Settings | Feature flag, display modes, tmux/iTerm2 setup | | Permissions | Permission presets for dev, prod, and read-only teams |

Controls

| Action | Key | |:---|:---| | Select teammate | Shift+Up/Down | | Toggle task list | Ctrl+T | | Delegate mode | Shift+Tab | | View teammate session | Enter | | Exit teammate view | Escape |

The one rule

No two teammates should edit the same file. Set file ownership in your CLAUDE.md and spawn prompts. Everything else is flexible — this isn't.

Tests

npm test

61 tests covering commands, harness install flows, validation, template integrity, and package structure. Zero dependencies.

Contributing

See CONTRIBUTING.md.

License

MIT

Links

Agent Teams docs · Subagents