Teams

Spawn several agents on the same task with explicit dependencies, isolated failure domains, and optional worktrees.

The shape

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

Worktrees are opt-in: --enable-worktrees enables them for the team and every teammate names one with --worktree. Without those flags, teammates use the configured working directory. --watch streams a live status board, 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 completed. In each wave, every ready node is attempted independently: one launch failure does not prevent another ready node from starting.

# 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

A permanent launch failure is recorded on that teammate with structured stage, code, message, exit_code, retryable, and observed_at fields. Only its descendants become blocked; independent branches continue. A transient placement failure caused by capacity or load stays PENDING with retryable evidence so a later wave can attempt it again.

After viable work drains, a no-watch teams start whose next wave produces only failures reports Failed this wave and returns nonzero. Status output preserves each cause instead of reducing a failed launch to a missing teammate.

Correct and retry a permanent failure

If the teammate itself can be resumed, teams resume clears stale failure evidence as the replacement enters RUNNING. If a permanent configuration error requires changing the teammate definition, remove the failed record before adding that name again; on a worktree team, teams stop first frees the old worktree.

agents teams stop pricing be          # already terminal — frees its clean worktree
agents teams remove pricing be
agents teams add pricing claude "rewrite endpoint" --name be --worktree backend
agents teams start pricing --watch

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

• Worktrees — underlying isolation model teams use.
• Sessions — teammates' output lands here.
• Cloud dispatch — run teammates on remote infrastructure.