Code review with Codex: one standard across CLI, desktop app and GitHub

Codex code review is one reviewer behind several triggers: /review and codex review locally, codex exec review in scripts, and @codex review or automatic reviews on GitHub pull requests. A single ## Review guidelines section in AGENTS.md steers all of them. The review earns trust only after a seeded-bug check shows it catches the defect classes the team cares about.

This page is for developers and tech leads who already get Codex reviews on single changes and now want them as a team gate. Your team opens more pull requests than it can read, half of them written by agents. One engineer’s Codex review flags everything, another’s flags nothing, and nobody knows whether a clean review means a clean change. The workflow below turns Codex review into a layered, measured gate with a clear line where humans take over.

If you have not run a Codex review yet, start with review Codex’s changes before you commit, which covers /review, the P0 to P3 findings and triage. Repository setup for @codex review is in connect Codex to GitHub.

What you’ll walk away with from team-wide Codex review

• A map of which Codex review surface belongs at which point in the pipeline, and what each one can block.
• A pre-push hook that runs codex exec review and blocks the push on P0 or P1 findings.
• A rollout order for @codex review, @codex security review and automatic reviews that keeps the noise down.
• A way to write AGENTS.md review rules from your own pull request history, not from a generic list.
• A seeded-bug check that tells you what the reviewer catches before anyone relies on it.
• A human escalation list: the changes a person still signs off on, whatever Codex says.

Which Codex review surface belongs where in your pipeline?

All surfaces are steered by the same AGENTS.md review rules. They differ in who triggers them, what scope they see and whether they can stop a change.

Surface	Triggered by	Scope	Can it block a change?
/review in the TUI	The author, mid-session	Uncommitted, base branch, one commit, or custom instructions	No, it informs the author
codex review (shell)	The author, from the terminal	--uncommitted, --base BRANCH or --commit SHA	No
codex exec review (script)	A Git hook or CI job	Same flags, plus -o, --json and the other exec options	Yes, when a script reads its output
Codex desktop app (codex app, or /app from the TUI; macOS and Windows)	The author, visually	The session’s changes	No
@codex review on a pull request	Anyone who comments	The pull request’s changes	Only if your merge rules require its comments resolved
Automatic reviews	Every new pull request	The pull request’s changes	Same as above
@codex security review	Anyone who comments	The pull request, security focus	Same as above

The order matters more than the choice. Cheap, private checks run first, so the public pull request review sees fewer defects and its comments stay worth reading:

1. Before commit: the author runs /review or codex review --uncommitted and fixes P0 and P1 findings.
2. Before push: a pre-push hook runs codex exec review --base origin/main and blocks on P0 or P1.
3. On the pull request: @codex review (and later, automatic reviews) posts findings where every reviewer sees them.
4. On risky paths: @codex security review for authentication, input handling and secrets, plus a named human owner.
5. Before merge: CI gates (tests, types, lint) and the human escalation list decide. Codex’s review is an input, not the approval.

Write review rules from your own pull request history

Codex reads ## Review guidelines in AGENTS.md. The local review prompt in Codex CLI 0.157.1 also tells the reviewer to read AGENTS.override.md and AGENTS.md for the changed files and to cite the rule behind a finding. That citation is your first verification tool: a finding that names a rule tells you the rule is working.

Generic rules (“check error handling”) repeat what the reviewer does anyway. The rules worth writing come from defects your team has already shipped or caught late. Let Codex draft them from your history, then cut hard.

Copy-paste prompt: draft review rules from the last 50 merged pull requests

Read the last 50 commits on main's first-parent history (git log --first-parent -50 main,
plus the diffs), and every
commit whose message starts with "fix" or "revert" in the last six months. Find defect
patterns that a reviewer could have caught from the diff: the file path, the wrong
pattern and the right one. Propose at most 10 rules for a "## Review guidelines" section
in AGENTS.md. Each rule must name a path or file pattern, a condition someone can check
from the diff, and a severity (P0 or P1). Do not propose rules about formatting, naming
or anything our linters already enforce. Do not edit any file; print the rules and, for
each one, the commit that motivated it.

A rule set that survives that filter looks like this:

## Review guidelines

- P0: any change under migrations/ that drops or renames a column without a matching
  backfill step in the same pull request.
- P1: an HTTP handler under src/api/ that reads req.body without a zod schema.
- P1: money handled as a float anywhere under src/billing/; amounts are integer cents.
- P1: a test under tests/ that is deleted, skipped (.skip, xit) or loses its assertions.
- Do not comment on formatting, import order or naming; dprint and oxlint run in CI.

The last line keeps the review readable. Every comment spent on something a linter already enforces trains the team to skip Codex comments. Keep rules that must always apply in the root AGENTS.md. The sources checked on 2026-09-26 do not say how a GitHub review of a pull request that spans several packages picks up nested AGENTS.md files, so a package-level rule is a bonus, not a guarantee. The wider file is covered in AGENTS.md for Codex.

Block a push on P0 and P1 findings with codex exec review

A review that the author can skip is advice. A pre-push hook makes the private review a gate, and it costs one Codex run per push, not per commit.

#!/usr/bin/env bash
# .githooks/pre-push: block the push when Codex reports a P0 or P1 finding
set -euo pipefail

git fetch --quiet origin main
codex exec review --base origin/main --ephemeral -o .codex-review.md

if grep -qE '\[P[01]\]' .codex-review.md; then
  echo "Codex review found P0/P1 findings. Read .codex-review.md, fix or disprove them."
  exit 1
fi

Enable it once per clone with git config core.hooksPath .githooks and chmod +x .githooks/pre-push, and add .codex-review.md to .gitignore. The flags were checked against codex exec review --help in 0.157.1: --base picks the scope, --ephemeral keeps the run out of your saved sessions, and -o writes the final review message to a file.

The bundled review prompt asks the reviewer to start each finding title with its priority tag, for example [P1]. Before you trust the grep, run the hook once on a branch with a known bug and check that the file contains the tag. That same run is the first data point of the seeded-bug check below.

Two constraints from 0.157.1 shape the hook. A scope flag and a custom prompt do not combine (--base main "focus on auth" fails), so the hook relies on AGENTS.md for focus instead of a prompt. And a same-session review shares the author’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, chosen from the models hub.

To run the same gate in CI, use the openai/codex-action setup in CI/CD with the Codex GitHub Action. Do not give a job that reviews pull requests from forks access to your API key: the reviewed branch supplies the AGENTS.md that steers the run.

Review pull requests with @codex review, then turn on automatic reviews

On a pull request in a connected repository, a comment starts the review. Codex posts its findings back on the pull request as review comments.

@codex review

Add a focus after the command when the pull request carries a specific risk. Keep the focus short and checkable; the AGENTS.md rules still apply underneath it.

Copy-paste prompt: review a pull request for API compatibility

@codex review for backward compatibility of the public HTTP API. Compare every changed
route under src/api/ with main: flag removed or renamed endpoints, removed or newly
required request fields, changed response field types, and changed status codes. Tag
each finding P0 if an existing client would break and P1 if it needs a migration note.
Ignore internal refactors that keep the wire format identical.

For changes that touch authentication, input parsing, file access or secrets, request the separate security pass that OpenAI documents for GitHub (verified in OpenAI’s GitHub integration guide on 2026-08-28):

@codex security review

Keep its findings with a named security owner rather than the pull request author; the scanner itself is covered in Codex Security. GitLab merge requests accept @codex review too (OpenAI’s GitLab integration guide, verified 2026-08-28).

Automatic reviews make Codex review each new pull request without a comment. Turn them on in the same Codex code review settings where you enabled the repository, and only after the rules are tuned. The order that keeps the noise down:

1. Weeks one and two: on-demand @codex review only, on pull requests the team picks. Record each finding as useful or noise.
2. Tune: every noise finding becomes a “Do not flag” line in AGENTS.md; every miss a human caught becomes a rule.
3. Seeded-bug check: run the check in the next section and keep the catch rate as your baseline.
4. Switch on automatic reviews for the repository. Keep on-demand only for public repositories with outside contributors.
5. Monthly: re-run the seeded-bug check and prune rules that never fire.

Automatic reviews do not replace required human approval

A clean Codex review means the reviewer found nothing it was looking for. Keep your branch protection’s required human approval for the paths on the escalation list below, and require CI to pass before merge.

The Codex desktop app shows the session’s changes too, and /app continues a TUI session there on macOS and Windows. 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). App workflows are in Codex desktop app mastery.

How do you know the Codex reviewer catches real bugs?

A reviewer that finds nothing looks identical to a reviewer that is blind. Measure it the way you would measure a test suite: plant defects and count what it finds.

Copy-paste prompt: build a seeded-bug branch to test the reviewer

Create a branch named refactor/tidy-handlers from main. On it, make exactly five small,
realistic defects, one per file, each matching a rule in the "## Review guidelines"
section of AGENTS.md or a common defect class: an off-by-one in a loop bound, a
swallowed exception, a missing auth check on one route, a float used for a money amount,
and a skipped test. Keep the code compiling and the other tests passing. Commit them as
one commit titled "refactor: tidy handlers and billing helpers". Do not write an answer key into the
repository, because the reviewer would read it. Instead, end your reply with the answer
key: each defect's file, line and the rule or defect class it violates.

The branch name and commit title are deliberately neutral: the reviewer sees both, and a name that announces planted defects inflates the catch rate. Then run codex exec review --base main -o seeded-review.md on that branch and compare the findings with the answer key you saved from the reply. Record three numbers per run: seeded defects caught, findings that were noise, and findings that cited a rule. Repeat after every change to the rules and at least monthly.

Evidence	What it proves	Who owns it
Seeded-bug catch rate, tracked per run	The reviewer finds the defect classes you care about	Tech lead
Findings closed with a failing-then-passing test, or withdrawn	A finding was real, not argued away	Pull request author
Noise rate on real pull requests (findings marked “not useful”)	The review stays worth reading	Team, reviewed at retro
CI gates green: tests, types, lint	Existing behaviour still holds	CI
Human approval on escalation paths	A person accepted the risk where a miss is expensive	Named code owner

The human escalation list is short and explicit: database migrations, authentication and authorisation, money movement, cryptography, public API contracts, and any change that edits tests or CI configuration. Put it in CODEOWNERS so branch protection enforces it. Everything else can merge on green gates plus a clean Codex review, which is how reading moves from the diff to the evidence. The pull-request version of that triage is in reviewing an agent’s pull request without reading every line, and the manifest an agent’s pull request should carry is the evidence bundle.

What breaks when Codex reviews every change?

The team stops reading Codex comments. The rules produce too many P2 and P3 findings. Add “Report only P0 and P1 findings on pull requests” and one “Do not flag” line per recurring noise category to AGENTS.md, then re-run the seeded-bug check to confirm the catch rate did not drop.

@codex review gets no response. Code review is not enabled for that repository, or the Codex GitHub connection cannot see it because of organisation permissions. Re-check both in the setup steps of connect Codex to GitHub.

The pre-push hook passes a change that has a P1 bug. The grep found no [P1] tag because the output format differs on your version, or the scope was wrong. Open .codex-review.md, check how findings are written, and adjust the pattern. Run the hook on the seeded-bug branch after every Codex upgrade.

codex exec review rejects the command. In 0.157.1 --base, --uncommitted and --commit cannot be combined with a custom prompt (“cannot be used with ‘[PROMPT]’”). Drop the prompt and move the focus into AGENTS.md, or drop the flag and name the scope inside the prompt.

Comments land on the wrong lines. Someone pushed while Codex was reviewing. Re-request @codex review after the last push, and ask authors to push once, not in a stream of small commits.

The reviewer agrees with the code it wrote. The same model reviewed its own output in the same session. Set review_model to a different model, run the review in a fresh process, and rely on tests over opinions.

Codex misses a domain rule every time. It is not in AGENTS.md, or it sits only in a nested file that the pull request review did not apply. Move it to the root file, phrase it as a checkable condition on a path, and add a seeded defect for it.

Where to go next with Codex code review

Review strategies for Codex output Tier review depth by risk and pick approval modes that do not bottleneck the team.

PR automation with Codex Take a pull request from worktree to merge, with review and CI fixes along the way.

Running the review queue when agents open the pull requests WIP limits, pull request size budgets and risk routing for a team's review load.

AI code review bots compared Codex review beside Claude Code Review, Bugbot and third-party bots.

Using another agent as well? The same pipeline for Claude Code is in review automation with Claude Code, and for Cursor in code review with Cursor.