A Codex CLI workflow that holds up on a Tuesday

The Codex CLI workflow, four steps

Every good Codex CLI workflow we have seen in the wild collapses to the same four moves, in this order. Teams that skip step one spend their time in code review instead.

• Plan in read-only. Start the session with the agent unable to write. Ask for the approach and the list of files it intends to touch. Argue with it here, where an argument costs a sentence rather than a diff.
• Execute in an isolated tree. A branch at minimum, a worktree if anything else is running. git worktree add ../wt-fix -b fix/session-leak keeps a bad run from contaminating your main checkout.
• Verify with one command. Decide it before you start. make test, a targeted test file, a grep that must return nothing. Put it in the prompt so the agent can check itself.
• Review the diff, not the transcript. The conversation is persuasive. The diff is the truth. git diff --stat first, then read the files that surprise you.

Session length is the thing nobody manages

The most common cause of a Codex session going sideways is that it has been open too long and covers three unrelated topics. Early context is still in there, quietly pulling decisions in the wrong direction. A refactor discussion from 40 minutes ago starts leaking into a bug fix.

Our rule is one session per task. Finish, commit, start fresh. If the task is long enough that you need to stop and come back, resume deliberately rather than leaving it open and drifting, and re-state the goal in the first message of the continuation. It feels wasteful. It is much cheaper than the diff you would otherwise have to unpick.

Put the boring things in config, not in your head

~/.codex/config.toml is where your sane defaults belong. Approval behaviour and sandbox level in particular, because those are the settings people override under pressure and then forget they overrode. Set the default conservative so the safe path is the lazy path.

At the repo level, AGENTS.md carries what the agent cannot infer. Keep it to a page. Ours typically has the build and test commands, the directories that are generated or legacy, the logging convention, and one line about what CI enforces. Everything else people want to add belongs in normal documentation.

Where this workflow does not help

It does not help when the test suite takes 25 minutes, because the verify step stops being a loop and becomes a coffee break. Fix a fast subset first. It does not help on tasks where you cannot state the acceptance condition, which usually means the task is exploratory and wants a human. And it does not compensate for a repo where nothing is tested, because then the verify step is your own judgement and you are back to reading every line.

Start here

Take your next bug fix and run only step one and step three: plan in read-only, and decide the verification command before any code exists. Ignore the rest. Those two habits carry most of the benefit, and they are the two that survive a busy week.

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