Parallel work with teams

Four agents on four files. Boundary contracts keep them from colliding.

Why parallel

Single-threaded editing is the failure mode of an agent run. The agent reads the auth module, edits it, reads the UI, edits it, reads the migration, edits it, runs the tests, runs the build. Each step pays a context tax. Half the run is reloading state the previous step already had.

Most large changes are not actually one change. They are three or four independent surfaces that happen to land in the same PR. Cut them apart and run an agent per surface and the whole thing finishes in the time of the longest single thread.

When not to use teams

Teams have setup cost. Skip them for a single-surface bug — one file, one fix, one test. Skip them for exploration — spawn a one-shot Agent subagent instead and let it read freely. Skip them when one teammate's output is genuinely required as another's input with no clean interface in between; sequencing two agents back-to-back is fine, but if A is constantly reading B's in-flight edits the split is wrong.

Create a team

agents teams create my-feature

A team is a named, persistent group of teammates with a shared task root. The name is used by every subsequent agents teams subcommand.

Add teammates with boundary contracts

Each teammate gets a prompt that names the files it owns and the files it must not touch. The contract is not a suggestion — it is the only thing standing between a coordinated team and four agents fighting over the same lines.

agents teams add my-feature claude "Owns: src/auth/*. Not: src/ui/*. Implement OAuth refresh." --name auth
agents teams add my-feature codex  "Owns: src/ui/login.tsx. Not: src/auth/*. Wire login UI." --name ui --after auth

The auth teammate owns src/auth/* and is explicitly told not to touch src/ui/*. The ui teammate owns one file and is told not to touch auth. --after auth sequences the UI work to start once the auth work commits, because the UI imports the new auth API and there is no clean interface to stub.

Start and watch

agents teams start my-feature --watch

--watch tails the live state of every teammate — current tool call, last assistant message, files edited so far — in one terminal pane. Drop it for headless runs; the team continues in the background and you read the result with agents sessions.

Verify after

agents teams status my-feature --json
grep -r "refreshToken" src/auth

The JSON status reports per-teammate exit code, file list, and final assistant turn. Read it, then verify with grep that the files you expected to change actually changed. A files_modified: [] for a teammate does not always mean failure — the teammate may have read the problem, decided the change belonged elsewhere, and left a note. Read the transcript before re-running.

What this looks like as a harness

The boundary contract is the harness. You wrote it once in the agents teams add prompt and every teammate respects it because it is in the first system turn they read. There is no coordinator process, no merge queue, no “ask the other agent before editing this file.” The contract is the coordinator. When a teammate considers reaching across the line, the prompt is right there reminding it not to.

The mistake you are engineering out is the cross-file collision. Write the contract, and the collision is structurally impossible.