v1.20.60see what's new →

Teams

Spawn several agents on the same task, each in its own worktree, with explicit dependencies between them.

The shape

agents teams create pricing
agents teams add pricing claude "rewrite endpoint" --name be
agents teams add pricing codex  "build route"      --name fe
agents teams add pricing claude "run tests" --name qa --after be,fe
agents teams start pricing --watch

Each teammate gets its own isolated copy of the repo (a git worktree) and runs independently until its --after dependencies are satisfied. --watch streams a live status board to the terminal, firing new waves as dependencies complete, then exits when the DAG drains.

Boundary contracts

Before spawning, declare what each teammate owns, what it must not touch, and which shared artifacts one teammate produces for others to consume. This is the only coordination mechanism that runs before the agents start — once they are running, violations cause merge conflicts or silent data loss.

auth teammate  — owns src/auth/* (all files)
               — must NOT touch src/ui/*, src/api/*
               — produces: src/auth/types.ts (shared dep)

ui teammate    — owns src/ui/login.tsx
               — must NOT touch src/auth/*
               — imports: src/auth/types.ts (read-only)
               — must NOT start until auth is done (--after auth)

The independence test: if teammate A must wait for B's output before A can start, the boundary is wrong. Re-cut the split so each teammate starts from the same baseline, or sequence them with --after.

DAG dependencies

Real work rarely parallelizes cleanly. --after tells the supervisor not to start a teammate until all named predecessors are in the completed state. The supervisor runs in a wave loop, draining ready teammates each pass.

# QA waits for backend AND frontend
agents teams add pricing-page claude "Run Playwright suite" --name qa --after backend,frontend

# Watch: supervisor fires qa only when both complete
agents teams start pricing-page --watch

Teammate state transitions: PENDING → RUNNING → COMPLETED (or FAILED / STOPPED). The state machine lives on disk, so the supervisor can be restarted mid-flight without losing work.

Worktree isolation

When hard filesystem isolation is needed — teammates editing the same file area — use --enable-worktrees at create time and assign each teammate a dedicated worktree with --worktree.

agents teams create parallel-refactor --enable-worktrees

agents teams add parallel-refactor claude   "Refactor auth module" --name auth --worktree refactor-auth

agents teams add parallel-refactor codex   "Refactor billing module" --name billing --worktree refactor-billing

agents teams start parallel-refactor --watch

Worktrees are cleaned up on teams stop or teams disband unless uncommitted changes are present, in which case the worktree is kept and reported. See worktrees for the underlying model.

Cloud teammates

Any teammate can be dispatched to a cloud backend instead of running locally. Pass --cloud rush|codex|factory on teams add.

agents teams create backend-fix

agents teams add backend-fix claude   "Fix the flaky payment test" --name fixer   --cloud rush --repo acme/monorepo --branch main

agents teams start backend-fix
agents teams status backend-fix

Cloud teammates run to completion remotely. Their output lands in sessions and is visible via agents teams logs. See cloud dispatch for provider details.

Worked example

agents teams create docs-update

agents teams add docs-update claude   "Rewrite docs/api.md — cover every endpoint in src/routes/"   --name api-docs

agents teams add docs-update codex   "Update docs/config.md — document every option in src/config.ts"   --name config-docs

# Both start immediately (no --after dependency)
agents teams start docs-update
agents teams status docs-update

Status and logs

agents teams list                    # all teams, most recent first
agents teams status pricing-page     # per-teammate state
agents teams logs qa                 # raw stdout from the qa teammate
agents teams active                  # all teammates running right now

Pass --json to any command for machine-readable output. teams start --watch --json emits one JSON object per wave — pipe to jq for dashboards.

Resume a stopped teammate

A teammate often ends its turn with more to do — a PR opened and waiting on review, a headless run that hit a turn cap, a task you want to redirect after the fact. agents teams resume re-enters that teammate's own session with your message as the next user turn, so it picks up with full context instead of you finishing the work by hand or spawning a fresh, context-less teammate.

# A teammate finished with its PR open, waiting on review. Nudge it home:
agents teams resume my-team backend "review's in — merge the PR, then cut the release"

# teams message is the same command, auto-routed by the teammate's state:
agents teams message my-team qa "skip the flaky screenshot test for now"

teams message routes by the teammate's current state: a running teammate is steered via its mailbox (delivered at its next tool call, no re-launch); a stopped one (completed / failed / stopped) is resumed — re-entering its session; a pending one is rejected until you teams start it. The resume re-launches through the same backend the teammate first used, in its original worktree, and flips it back to running.

Every harness. Resume delegates to agents run --resume — native resume for Claude and Codex, and a universal /continue replay for the rest (OpenCode, Grok, Kimi, …).

Related