# Review Codex's changes before you commit URL: https://developertoolkit.ai/en/codex/quick-start/review-workflow/ Description: Check Codex's work without reading every line: run your gates, run /review or codex review, triage P0–P3 findings, keep good hunks with Git, then 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](/en/codex/quick-start/first-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 `## Code Review Rules` 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** ```text 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** ```bash 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 ' 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** ```bash 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](/en/codex/ship/ci-cd/). **Copy-paste prompt: a focused custom review** ```text 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](/en/ecosystem/models/) 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. ```markdown ## Code Review Rules - 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](/en/codex/quick-start/github-integration/). The wider file is covered in [AGENTS.md for Codex](/en/codex/quick-start/agents-md/). ## 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** ```text 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** ```text 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. ```bash 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 `. **Copy-paste prompt: redo a file you reverted** ```text 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. ```bash 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](/en/codex/automate/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](/en/codex/build/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](/en/workflows/ship/agent-pr-review/); to stop Codex editing the tests that judge it, see [protecting the oracle](/en/workflows/test/protect-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 ` to list them and `git clean -f ` 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](/en/codex/quick-start/error-recovery/). ## Where to go next with Codex reviews - [Set up MCP servers for Codex](/en/codex/quick-start/mcp-setup/) — Give Codex live access to your issue tracker, docs and databases. - [Recover when Codex goes wrong](/en/codex/quick-start/error-recovery/) — Sandbox errors, wrong-direction edits, loops and Git checkpoints. - [Code review with Codex across surfaces](/en/codex/ship/code-review/) — Review on every change: CLI, desktop app and GitHub, with shared rules. - [Review strategies that do not bottleneck the team](/en/codex/ship/review-strategies/) — Tiered review and approval modes for Codex output at team scale.