Review Codex's changes before you commit

The Codex review workflow is the loop between “Codex says it is done” and a commit: run the project’s own tests and type checks, run /review or codex review for a separate read-only pass, fix or dispute each prioritised finding, keep the good hunks with Git and discard the rest. Evidence decides the commit, not the agent’s summary.

This page is for developers who have run their first Codex task and now face the result. Codex reports “Done, all tests pass”, the diff touches nine files, and you have a meeting in 20 minutes. Reading every line is too slow; committing on trust is how a swallowed exception reaches production. The loop below takes about as long as the meeting prep and leaves you with proof instead of a feeling.

What the Codex review loop gives you

• A fixed order for checking a Codex change: evidence, gates, review pass, triage, partial accept, commit.
• The exact /review, codex review and codex exec review forms for Codex CLI 0.157.1, including the flag combination that fails.
• A ## Review guidelines block for AGENTS.md that the reviewer cites back to you.
• Git commands that keep some hunks and drop others without losing work.
• Five copy-paste prompts: ask for evidence, run a focused review, fix findings, prove or withdraw a finding, and redo a reverted file.

What order should you check a Codex change in?

Cheap, objective checks come first, and your attention comes last, spent only where the checks point.

1. Ask for evidence. Get the list of changed files, the commands Codex ran and their exit codes, and every test it added, changed, skipped or deleted.
2. Run the gates yourself. Tests, type check and lint, in your terminal, not in Codex’s summary.
3. Run a review pass. /review in the TUI or codex review from the shell. The review runs in its own pass, with instructions to find defects rather than defend the code.
4. Triage findings. Fix P0 and P1, turn doubtful findings into failing tests, record P2 and P3.
5. Keep what is good. Stage the good hunks, restore the bad ones, and send Codex back for a narrow redo.
6. Re-run gates and review on what is left, then commit. A second pass on a smaller diff is fast.

Copy-paste prompt: ask Codex for evidence before you review

Before I review, list every file you changed and one line on why. Then list the exact
commands you ran to verify the change, with their exit codes, and every test you added,
changed, skipped or deleted. Do not change any code in this turn.

A test that Codex skipped or deleted is the single most important line in that answer. Skipping or deleting a test is the cheapest way an agent turns a red suite green, and it never shows up in a “tests pass” summary.

Run a review with /review or codex review

Codex CLI 0.157.1 has three entry points to the same review behaviour. They differ in where you run them, not in what they check.

TUI: /review

Type /review with no arguments to open the preset picker:

• Review against a base branch: the whole branch, like a pull request.
• Review uncommitted changes: staged, unstaged and untracked files.
• A commit: pick one from a searchable list titled “Select a commit to review”.
• Custom review instructions: your own text.

Type /review followed by text to skip the picker and run a custom review with that text as the instructions. Codex does not start /review while a turn is still running, so wait for the task to finish first. /diff shows the raw git diff, including untracked files, without leaving the session.

Shell: codex review

codex review --uncommitted        # staged, unstaged and untracked changes
codex review --base main          # everything the branch adds on top of main
codex review --commit HEAD        # the last commit only
codex review "Review the uncommitted changes. Focus on error handling in src/api/."

--uncommitted, --base and --commit are mutually exclusive, and none of them can be combined with a custom prompt: codex review --base main "focus on auth" fails with the argument '--base <BRANCH>' cannot be used with '[PROMPT]' (checked on 0.157.1). Pick a preset, or name the scope inside the prompt. The command needs a Git repository or a trusted directory.

Script: codex exec review

codex exec review --base main -o review.txt       # final review text to a file
codex exec review --uncommitted --json            # JSONL events for a script to parse

codex exec review takes the same scope flags plus the usual exec options, such as --model, --output-schema, --ephemeral and --skip-git-repo-check. Use it in a pre-push hook or a CI job; the full CI setup lives in CI/CD with the Codex GitHub Action.

Copy-paste prompt: a focused custom review

Review the uncommitted changes in this repository against origin/main. Report only
defects you can tie to a specific line: wrong behaviour, missing or swallowed error
handling, unhandled edge cases (empty input, null, concurrency, time zones), security
issues, and tests that were weakened, skipped or no longer assert anything. Ignore
formatting and naming. Tag each finding P0 to P3 and end with an overall verdict.

Paste it after /review in the TUI, or pass it as the only argument to codex review.

What the review output tells you

The review prompt bundled in Codex CLI 0.157.1 asks for findings the author would actually fix, one per issue, each on a short line range and tagged P0 (drop everything) to P3 (low). It tells the reviewer to ignore style, formatting and typos, and to end with an overall verdict: “patch is correct” or “patch is incorrect”. An empty findings list is a legitimate result, not a failure.

When you run the review from the TUI in the same session that wrote the code, the reviewer shares that session’s model. To get a second opinion from a different model, set review_model in ~/.codex/config.toml to another model from your /model list. The models hub has the current line-up.

Write review rules the reviewer cites back to you

Generic correctness advice is what every reviewer produces. Your repository’s rules are what make a review worth running. The same prompt tells the reviewer to read AGENTS.override.md and AGENTS.md for the changed files (the more specific file wins) and to cite the file and line of any rule behind a finding.

## Review guidelines

- Money is integer cents. Flag any floating-point arithmetic on an amount as P1.
- Every new route in src/api/ validates its input with zod. Flag a missing schema as P1.
- tests/contract/ is owned by the platform team. Flag any edit there as P0.
- Do not flag formatting: dprint runs in CI.

Put this block in the root AGENTS.md, or in a nested one for a single package. The same heading also steers @codex review on GitHub pull requests, which is set up in Connect Codex to GitHub. The wider file is covered in AGENTS.md for Codex.

Triage the findings: fix, prove or record

Treat each finding as a claim that needs the same evidence as the code did.

Finding	What you do	Evidence that closes it
P0 or P1 you agree with	Send it back to Codex with the fix prompt below	A new test that fails before the fix and passes after it
P0 or P1 you doubt	Ask Codex to prove it	A failing test, or Codex withdraws the finding
P2 or P3	Record it in the pull request description or an issue	Nothing now; do not grow this diff
Finding cites an AGENTS.md rule	Fix it, or change the rule if the rule is wrong	The rule and the code agree

Copy-paste prompt: fix the blocking findings

Fix the P0 and P1 findings from the review above, one at a time. For each fix, add or
update a test that fails without the fix and passes with it. Do not touch code that no
finding points at. Leave P2 and P3 findings alone and list them at the end. Run the full
test suite and the type check, and paste their summary lines.

Copy-paste prompt: prove a finding or withdraw it

For the finding "[P1] Retry loop never gives up on 429" show me a concrete input or call
sequence that triggers it, and write that as a test in the existing test file for this
module. Run the test. If you cannot make it fail against the current code, say so and
withdraw the finding instead of changing the code.

The second prompt is how you check a review without reading the code behind it: a finding that produces a failing test is real, and one that cannot is noise you can drop with a clear conscience.

Keep the good hunks and discard the rest with Git

Codex edits your working tree, so every Git tool you already use works on its output. The pattern that saves the most time is the partial accept: keep the files that are right, restore the ones that are wrong, and send Codex back for a narrow redo.

git diff > ../codex-task.patch       # safety copy of tracked changes before you discard any
git add -p src/api/orders.ts         # stage hunk by hunk: y keeps a hunk, n skips it
git add src/api/schemas.ts           # stage a whole file you trust
git restore -p src/lib/cache.ts      # discard selected unstaged hunks
git restore src/billing/invoice.ts   # discard a whole file's unstaged changes
git clean -n src/                    # list new untracked files Codex created
git diff --staged                    # exactly what the commit will contain

git restore discards changes permanently, and it never removes files Codex created: those are untracked, so list them with git clean -n before you delete anything with git clean -f <path>.

Copy-paste prompt: redo a file you reverted

I reverted your changes to src/billing/invoice.ts with git restore. Re-implement only the
rounding fix in that file. Keep every exported function signature unchanged and pass the
tax-rate lookup in as a parameter instead of importing it. Do not edit any other file.
Run the invoice tests and paste the result.

When the redo lands, run the gates again and run codex review --uncommitted on what is left. Then commit the staged set with a message that names the task, not the tool.

Review work from Codex cloud and the desktop app

Cloud tasks run away from your machine, but you can still review their diff before it becomes a pull request. codex cloud is marked experimental in 0.157.1.

codex cloud list                      # recent cloud tasks and their ids
codex cloud diff TASK_ID              # the task's unified diff, printed locally
codex cloud apply TASK_ID --attempt 2 # apply attempt 2 of a best-of-N task to your tree
codex review --uncommitted            # then review it like local work

TASK_ID is the id that codex cloud list prints. Applying locally lets the same gates and the same review pass run on cloud work. Environment setup and best-of-N attempts are covered in Codex cloud environments.

codex app and the /app slash command (macOS and Windows) continue the current session in the desktop app; what the app shows is covered in Codex desktop app mastery. OpenAI’s README still calls it the Codex App; since 2026-07-09 it ships as the Codex mode of the ChatGPT desktop app (secondary: Neowin, 2026-07-09).

How do you know the change is right without reading every line?

The review pass is one signal, not an approval. Decide in advance which evidence proves what, and read only the lines the evidence cannot cover.

Evidence	Produced by	What it proves
Tests, type check and lint, run by you	Your toolchain	The change builds and existing behaviour still passes
New tests mapped to the task’s acceptance criteria	Codex, on request	Each criterion has a test that fails without the change
No skipped, deleted or loosened tests	The evidence prompt plus git diff --stat tests/	Codex did not buy a green suite by weakening it
Review findings closed with tests or withdrawn	/review or codex review	The known defects are fixed, not argued away
Your own read of risky paths	You	Auth, money, migrations and concurrency got human eyes

You still sign off. What changes is where your reading goes: to the test diff and to the few paths where a mistake is expensive. For the pull-request version of this triage, see reviewing an agent’s pull request without reading every line; to stop Codex editing the tests that judge it, see protecting the oracle.

What breaks in the Codex review loop?

codex review rejects your prompt. The message is “cannot be used with ‘[PROMPT]’”. A scope flag and custom instructions do not combine in 0.157.1. Drop the flag and write the scope into the prompt (“Review the changes on this branch against main…”).

“Not inside a trusted directory and —skip-git-repo-check was not specified.” codex review needs a Git repository or a trusted directory. Run git init and commit a baseline first, so the review has something to diff against. codex exec review also accepts --skip-git-repo-check.

The review finds nothing, but the diff is large. Check the scope. --uncommitted misses work Codex already committed; use --base main or --commit HEAD. A clean verdict on the wrong scope is the most convincing false negative there is.

The reviewer agrees with the author. A same-session review shares the author’s model and context. Set review_model to a different model, run codex review in a fresh terminal, and lean on tests rather than on a second opinion.

Tests pass because Codex changed them. Run git diff --stat on your test directories before you trust a green suite. Put the rule “flag any edit to tests/contract/ as P0” in AGENTS.md, and make CI own the checks Codex cannot touch.

git restore did not remove a file. New files are untracked. Use git clean -n <path> to list them and git clean -f <path> to delete them.

A cloud patch does not apply. Your branch moved since the task started. Commit or stash local work, pull, and apply again, or try another --attempt. If it still conflicts, ask for a new cloud task on the current branch. More recovery patterns are in error recovery for Codex.

Where to go next with Codex reviews

Set up MCP servers for Codex Give Codex live access to your issue tracker, docs and databases.

Recover when Codex goes wrong Sandbox errors, wrong-direction edits, loops and Git checkpoints.

Code review with Codex across surfaces Review on every change: CLI, desktop app and GitHub, with shared rules.

Review strategies that do not bottleneck the team Tiered review and approval modes for Codex output at team scale.