Running an agent team in Codex without chaos

What an agent team on Codex is good for

Running an agent team in Codex means several runs working at once on separate slices of the same problem. It pays off in a narrow band, and the band is narrower than the demos suggest.

Where it works: tasks that are genuinely independent and touch disjoint files. Adding test coverage across five unrelated modules. Migrating twelve call sites of a deprecated helper, one agent per package. Reading a large unfamiliar service from three angles and reporting back, with no writes at all.

Where it fails: anything with a shared interface. Two agents editing the same type definition produce two plausible versions of it and you spend longer reconciling than you saved.

Isolate first, then parallelise

The mechanic that makes this workable is git worktrees. One directory per agent, one branch per agent, no shared working tree.

• git worktree add ../wt-auth -b agent/auth and repeat per slice
• Start a Codex run in each directory with its own scoped task
• Let each one land a commit and push its branch
• Merge in an order you decide, running the full test suite after each merge, not at the end

Skip the isolation and you get the classic failure: two agents in one checkout, one runs npm install, the other is mid-edit, and the resulting state belongs to neither. We have watched this eat an afternoon more than once.

Every agent needs an exit condition you can check

With one agent you can supervise. With four you cannot, so each task has to carry its own proof. Write the command into the prompt: the module's tests pass, the type check is clean, the deprecated symbol no longer appears under grep -rn "oldHelper" src/. An agent with a checkable exit condition stops when it is done. An agent without one keeps going and starts improving things you did not ask about.

Non-interactive runs make this concrete. codex exec with a scoped prompt and a clear acceptance command gives you something you can wire into a script and inspect afterwards, rather than four terminal panes you are trying to watch at once.

The coordination cost nobody budgets for

Four agents produce four diffs, and a human still reads all of them. If your review capacity is the bottleneck, parallelism makes it worse, not better. We tell teams to measure this honestly for two weeks before scaling up: time from task start to merged, not time to first diff. Plenty of teams discover their one-agent flow was already saturating the reviewer.

The other cost is context loss. Agent three does not know what agent one decided. Whatever convention you want them all to follow has to live in AGENTS.md, because it will not travel between sessions any other way.

A first experiment worth running

Take a chore you have been putting off, something like adding tests to modules nobody has touched in a year. Split it by directory, three worktrees, three agents, one acceptance command each. Merge them yourself, one at a time, with tests between. Note where the conflicts came from. That list is the real answer for how far your codebase can be parallelised, and it beats any general advice including this article.

We run this exercise on client repos as part of a training day, because the failure modes are specific to how your code is organised.

If you want help putting this into practice, talk to us.