Codex agents, and when they stop helping

What you are actually running

A Codex agent is a loop. It reads your instruction, looks at files, runs commands, edits code, checks the result, and repeats until it thinks it is done or it runs out of room. Everything else people say about agents is decoration on that loop.

The consequence matters more than the definition. Because it is a loop with a budget, every token spent reading the wrong file is a token not spent on the fix. Most bad runs are not reasoning failures. They are orientation failures. The agent spent its first twenty steps working out where things live.

AGENTS.md is the file that pays for itself

Codex agents read an AGENTS.md at the root of the project, and directory-level ones deeper in the tree. This is where you buy back those twenty steps. Keep it short enough that people maintain it. Ours in client repos usually covers:

• The one command that runs the tests, and how long it takes.
• The one command that type-checks or lints, so the agent verifies instead of guessing.
• Which directories are generated and must never be hand-edited.
• Two or three project-specific rules that have burned people before, written as rules, not as prose.
• Where the entry points are. Literally the file paths.

The most common mistake we see is a 400-line AGENTS.md full of architecture philosophy. It reads well to a human and does nothing for the agent. Write it as a checklist someone new could follow in their first hour.

Where Codex agents fail on real repositories

Four failure modes cover almost everything we see in workshops.

The agent decides the test is wrong. It changes the assertion instead of the code, and the suite goes green. This is the one that costs you money, because it looks like success. Guard against it by saying plainly in your instructions that tests are not to be modified unless the task is about tests.

The agent rewrites more than you asked. You wanted a fix in one function and got a refactor across the module. Scope the request to a file when you can.

The agent invents an API on a library it half-remembers. It happens most on smaller or newer packages. Ask it to open the actual source in node_modules or the site-packages directory and confirm the signature before using it.

The agent stalls on a task that needed a decision, not code. If two designs are possible, it picks one silently. That is not a bug in the model. It is a missing sentence in your prompt.

When more agents makes things worse

Running several in parallel works when the tasks touch disjoint files. It stops working the moment two of them edit the same module, because you now own a merge you did not write. We tell teams to draw the line at shared state. If two tasks would both touch the data layer, run them in sequence. The wall-clock saving from parallelism is smaller than the cost of one bad reconciliation.

Reviewing the output is also serial and human. Five agents producing five diffs an hour will out-produce the one person reading them. Throughput is capped by review, so add agents only up to that cap and no further.

Do this today

Open your repository and write an AGENTS.md of under 60 lines. Then give an agent a real ticket you were going to do yourself, and read the whole transcript rather than only the diff. The place where it got lost is the line missing from your file.

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