Build with Codex: context, isolation and gates

Building with Codex works when three things are set before the agent writes code: AGENTS.md and skills carry the project’s rules, each task runs in its own Git worktree, and a command you chose in advance decides when the task is done. Codex’s own summary is a claim to check, not the evidence.

This hub serves developers who use Codex daily and tech leads who set team defaults; the pages below keep work isolated and make every result prove itself. Checked against Codex CLI 0.157.1.

Which Codex build page answers your question?

Your question	Page
How do I make AGENTS.md and skills load, and prove they did?	Optimize AGENTS.md and skills for Codex
How do I phrase a task so Codex gets it right first time?	Effective prompting and AGENTS.md strategies
How do I stop long sessions drifting and hand work between threads?	Context management across Codex surfaces
Which commands and shortcuts are worth learning?	Codex CLI commands, slash commands and shortcuts
How do I run parallel threads in the desktop app?	Codex desktop app: parallel threads, worktrees and review
How do I make every session start faster?	Codex efficiency hacks
How do I build an endpoint I trust without reading the handler?	Build APIs with Codex
How do I prove a schema change or migration is safe?	Database work with Codex
How do I refactor hundreds of files safely?	Large-scale refactoring with worktrees
How do I apply one change across many packages or repositories?	Codex batch operations
How do I migrate a legacy codebase in waves?	Legacy code modernization with Codex
How do I keep docs and changelogs in step with the code?	Generate and maintain documentation with Codex

Before this stage: the Codex quick start and plan with Codex. Related: multi-agent workflows and build workflows for every tool.

In what order should a Codex build task run?

Each step closes one way for a finished-looking task to be wrong. The commands below are the CLI’s.

1. Check what Codex actually loads. From the repository root, render the model-visible input:

   codex debug prompt-input > /tmp/codex-input.json

   Since 0.150.0 an untrusted project does not supply its project-level AGENTS.md (the global ~/.codex/AGENTS.md still loads). Trust the repository by accepting the prompt Codex shows when a session first opens in it, then check the dump. The dump is JSON, so quotes, backslashes and line breaks from AGENTS.md appear escaped: grep for a short phrase from a single line with none of those characters, or add a unique sentinel word to AGENTS.md and grep for that. A non-zero count means your rules loaded:

   grep -c "<short phrase or sentinel from AGENTS.md>" /tmp/codex-input.json

2. Plan read-only. Start the session with codex -s read-only, or use /plan, and ask for the plan and the acceptance checks before any edit.

3. Build in a worktree. Start with codex --worktree, or /worktree in a session, so parallel tasks never share a working directory.

4. Gate on your commands, not Codex’s report. The tests, type check and lint named in AGENTS.md decide when the task is done; check their exit codes.

5. Review before commit. Run codex review --uncommitted in the worktree and fix every finding you would block a pull request on (correctness, security, data loss) before the branch reaches one.

Stay on the default model, GPT-6.1 Sol, and raise reasoning effort before you switch models. Codex runs GPT-6.1 Sol at low effort by default; raise it per session with /model. For signed-in accounts the server can set a different default model, so check /model for what you are actually running. The models hub has the current lineup.

Copy-paste prompt: plan a feature with acceptance checks

Read AGENTS.md and the modules this feature touches. Do not edit any files.
Feature: let users export their invoices as CSV from the billing page.
Write a plan with:
1. The files you will change or create, and why each one.
2. Acceptance checks as commands I can run (test names, a curl call, a typecheck),
   each with the result that proves the check passed.
3. The existing tests that must stay green, and any test you will add first so it
   fails before the change.
4. Anything in the plan that touches authentication, billing totals or a migration.
Stop after the plan and wait for my approval.

Copy-paste prompt: finish a worktree task with evidence

You are done implementing. Before you report back:
1. Run the test, typecheck and lint commands from AGENTS.md. Report each command
   and its exit code. Do not claim a result you did not run.
2. List every file you changed. Flag any change to a test, a fixture, CI config or
   a shared utility outside the feature's directory, with the reason.
3. Say which acceptance check from the plan each change satisfies, and which check
   is not covered by an automated test yet.
End with one line: DONE, or NOT DONE and what is missing.

How do you know a Codex build is right without reading every line?

Codex controls none of this evidence. Read it first, then open the diff only where it points.

Evidence	What it proves	Who owns it
codex debug prompt-input contains your rules	Codex worked with your conventions	Maintainer of AGENTS.md
A new test failed before the change and passes after	The change does what the plan promised	Developer
Full suite, type check and lint exit 0	Existing behaviour still holds	CI
codex review --uncommitted has no finding you would block a pull request on	No known defect by your own review rules	Developer
No unexplained change to tests, CI or shared code	Codex did not move the goalposts	Tech lead via CODEOWNERS

What goes wrong when Codex builds features?

Symptom	Cause	Recovery
Codex ignores a rule you wrote in AGENTS.md	Untrusted project, or the file is outside the loaded chain	Step 1, then move long procedures into a skill
One thread overwrites another’s edit	Both ran in the main checkout	Step 3
Codex reports “all tests pass” and CI fails	Codex ran a subset, or a different command	Name exact commands in AGENTS.md; require exit codes in the report
The fix works because a test was loosened	The agent can edit its own checks	Flag test changes in the finish prompt; put test paths under CODEOWNERS
A long session starts contradicting earlier decisions	Context was compacted and details were lost	Write a handoff file and continue in a fresh thread

Where to go next with building in Codex

Prove it with tests

Test and debug with Codex

Ship it

Review and ship with Codex

For the same stage in other agents, see build with Claude Code and build with Cursor.