Running a Codex team of agents without a mess

The test for whether parallelism helps

Before you run a Codex team of agents on a problem, ask whether you could hand the pieces to three contractors who never speak to each other. If yes, parallel works. If the pieces need to agree on an interface that does not exist yet, you will spend more time reconciling than you saved.

This piece covers running fully separate Codex sessions by hand. Codex also ships a native subagents feature that dispatches similar work to worker agents automatically, with isolation behavior that depends on the client and task, and it is worth checking first if you want less manual setup. The manual pattern below still matters when you need more direct control over isolation than the built-in dispatch gives.

Work that splits cleanly: a dependency upgrade across six services, adding a missing test file per module, a rename that touches many packages, porting a pattern you have already established once. Work that does not: designing the API those services will share, anything where the second task's correct behaviour depends on a decision made in the first.

Isolation is not optional

Two agents in one working tree will overwrite each other, and the failure is quiet. One finishes, the other's edits land on top, tests pass because they touch different files, and a week later you find the missing half.

Give each agent its own tree. Git worktrees are the cheapest way:

git worktree add ../repo-upgrade-auth -b upgrade-auth

Repeat per task, run one agent per directory, review the branches independently. The cost is disk space and a slower first build in each tree. Worth it.

• Use separate worktrees for concurrent edits that could conflict. Read-only tasks or deliberately serialized edits can share a checkout when repository policy allows.
• Write the brief for each task before starting any of them, so you notice the hidden dependency while it is still cheap.
• Merge in an order you chose deliberately, not in the order they finish.
• Run the relevant integration checks after combining changes and complete the required final suite. A final check can detect interaction bugs; intermediate checks can help locate which merge introduced one.

Where the ceiling is

Limit concurrency to the amount of output you can inspect and integrate. There is no universal task count that establishes adequate supervision. The bottleneck was never generation.

Watch for the specific failure of divergent solutions to the same sub-problem. Two agents both needing a date-formatting helper will write two different ones, in two different places, with two different edge-case behaviours. Neither is wrong on its own branch. Together they are technical debt you paid to create. Preempt it by naming the shared utilities in the brief, or by doing that piece yourself first.

Cost is worth a sentence too. Parallel sessions multiply token spend and you may be waiting on rate limits rather than on the work. Measure before you assume three agents finish in a third of the time.