What codex team mode actually means for a shared repo

The honest answer about codex team mode

People search for codex team mode expecting a toggle. What exists is a workspace that several seats share, plus the repo itself. Codex reads the same instruction files for everyone who runs it. That is the real shared surface. Getting a team working well is mostly about what you write into the repo, not about a setting in a dashboard.

We have watched teams discover this the slow way. Two engineers ask Codex for the same refactor within an hour. Both get plausible diffs. Neither knows the other asked. The tool did nothing wrong.

Put the shared rules in the repo

Codex picks up an AGENTS.md at the repo root and honours more specific ones deeper in the tree. Treat that file as the team contract. Ours usually covers four things:

• How to run tests and lint, as literal commands, not prose. pnpm test --run beats "run the test suite".
• Which directories are off limits. Generated clients, vendored code, migrations already applied in production.
• The commit and branch convention, so review does not turn into style arbitration.
• What the agent should do when it is unsure. Ours says: stop and ask, do not guess a schema.

Keep it short. A 400 line instruction file gets skimmed by humans and diluted for the model. When we cut one client's file from 380 lines to 90, their acceptance rate on first diffs went up, not down.

Claim the work before you start it

The failure that costs the most time is duplicated agent work. It is invisible until review. Fix it socially, not technically. The teams that handle this well do something dull: they post the task in a channel before launching an agent on it, and they push a branch immediately, even empty, so the name is taken.

Long-running cloud tasks make this worse because the work is happening while nobody is looking at a terminal. If your team runs those, agree on who owns each one and where the resulting PR lands.

What breaks when everyone runs an agent

Review capacity is the bottleneck, not generation. One engineer with Codex can open more pull requests than a team can read carefully. What we see when that goes unmanaged:

• Rubber stamping. A 900 line diff gets an approval in ninety seconds.
• Drifting conventions, because each agent run reinvents a helper that already exists two folders away.
• Test suites that grow faster than they get maintained, then get skipped.

The counter is a size limit the team enforces on itself. We suggest capping agent-authored pull requests at roughly what a reviewer can hold in their head, and splitting anything larger into stacked changes.

Start here this week

Write the AGENTS.md together in one sitting, out loud, as a group. Disagreements surface fast and the file ends up honest. Then agree on two rules: announce the task before you start, and no agent pull request lands without a human who can explain the diff. Revisit both after two weeks and cut whatever nobody followed.

That is the whole of team mode. Everything else is tooling preference.

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