Most pull requests bounce off human review for the same three reasons: missing tests, broken team conventions, and accidental side effects. OpenAI’s Codex now ships a purpose-built reviewer that catches all three before a human ever opens the diff — but only if you brief it with your team’s actual rules instead of letting it fall back on internet-average advice. This guide covers the exact /review command in the Codex CLI, the @codex review trigger on GitHub, and the AGENTS.md review-guidelines block that turns Codex from a vibe-checker into a reviewer that posts cited P0/P1 findings.
TL;DR
- Codex has a dedicated code reviewer (separate from the coding agent) that reads a diff and reports prioritized findings without touching your working tree.
- Run it locally with the CLI
/reviewcommand, or on GitHub by commenting@codex reviewon a pull request. As of June 2026, Codex is powered by GPT-5.5-Codex and is included in ChatGPT Plus ($20/mo), Pro, and Business ($30/user/mo) — there is no standalone Codex subscription. - On GitHub, Codex posts only P0 and P1 issues so the PR thread stays focused on real risks, not nits.
- It honors a
## Review guidelinessection in your top-levelAGENTS.md, applying the nearestAGENTS.mdto each changed file. - Treat it as the pre-pass, not the verdict: Codex catches convention drift and missing tests reliably; a human still owns business-logic judgment.
Who this is for
Engineering teams doing PR-based work, solo developers with no second reviewer, and tech leads who keep receiving PRs that “compile but feel wrong.” It is most valuable in fast-moving codebases where conventions have drifted and nobody has written them down.
When to skip it: trivial PRs under ~20 lines, where the round-trip costs more than it saves, and production hotfixes where speed outweighs thoroughness.
How Codex review actually works
Codex’s reviewer is trained specifically to catch high-severity flaws, and it differs from a linter in three ways:
- It matches the stated intent of the PR (title, description, commit message) against the actual diff, so it flags changes that quietly do more than the PR claims.
- It reasons over the surrounding codebase and dependencies, not just the changed lines, which is how it spots regressions in callers you forgot about.
- It surfaces three concrete categories by default: regressions, missing tests, and documentation gaps.
In GitHub it deliberately reports only P0/P1 findings. Locally, the CLI reviewer returns prioritized findings and never edits your files — each review is its own turn in the transcript, so you can re-run it as the code evolves and diff the feedback.
Before you start
- Write or update a top-level
AGENTS.mdwith a## Review guidelinessection listing your team’s real rules: naming, error handling, “never log PII,” “auth middleware wraps every route.” Codex applies the closestAGENTS.mdto each changed file, so package-level files can add stricter rules deeper in the tree. - Make sure CI is green on the base branch. Codex inherits a broken baseline as noise.
- Decide what “blocking” means for your team. Codex assigns P0/P1, but your taste makes the final call.
A minimal AGENTS.md block looks like this:
## Review guidelines
- Never log PII or secrets; flag any new logger call that touches user objects.
- Every new HTTP route must be wrapped by the auth middleware in src/middleware/auth.ts.
- New public functions require a unit test and a JSDoc block.
- Prefer Result<T, E> over throwing in the services/ layer.Path A — review locally with the CLI /review command
Inside an interactive Codex CLI session, type /review. It launches the dedicated reviewer with four preset modes:
| Mode | What it reviews | Use it when |
|---|---|---|
| Review against a base branch | Merge-base diff vs. upstream | Right before you open a PR |
| Review uncommitted changes | Staged + unstaged + untracked | Catch issues before you commit |
| Review a commit | The exact change set for a SHA you pick from the list | Auditing a specific commit |
| Custom review instructions | Same reviewer, your focus prompt | ”Focus on accessibility regressions” |
By default the reviewer uses your current session model. To pin a stronger model just for reviews, set review_model in ~/.codex/config.toml:
review_model = "gpt-5.5-codex"The reviewer reports prioritized, actionable findings and does not modify your working tree, so you can run it freely without fear of unwanted edits.
Path B — review on GitHub with @codex review
- Connect Codex cloud to your repo, then open the Codex code-review settings and enable the Code review toggle for that repository.
- On any PR, comment
@codex review. Codex reacts with 👀 and posts a standard GitHub code review with inline comments. - To scope a single run, add context in the comment:
@codex review for security regressions. - To run on every new PR automatically, turn on Automatic reviews in settings — no comment needed.
- When Codex flags something, ask it to fix it in a follow-up comment:
@codex fix the P1 issue. That spins up a cloud task that updates the PR.
Because GitHub reviews are limited to P0/P1, you will not get a 40-item nit wall on the PR thread; tighten the rest with your AGENTS.md guidelines.
The human handoff
- Run Codex first (CLI or GitHub). Triage every finding yourself — disagree with anything that conflicts with your context. The P0/P1 labels make disagreements explicit instead of buried in prose.
- Fix accepted P0/P1 items before requesting human review. Annotate the ones you are intentionally leaving.
- When tests are missing, ask Codex directly: “For the change in
auth.ts, propose 3 unit tests: invalid token, expired token, missing claims.” Implement what is reasonable; do not let it merge fixes unreviewed. - Hand off to your human reviewer with a one-line note: “Pre-reviewed by Codex; outstanding follow-ups in PR comments.” It saves their time and signals you read the diff yourself.
First-run calibration
Run Codex on a PR that already merged, then compare its findings to what the human reviewer actually wrote. The overlap is what Codex catches reliably. The gaps are instructive in both directions: Codex tends to miss subtle business-logic bugs that need product context, while humans miss tedious convention drift. If Codex missed something obvious, that rule is missing from your AGENTS.md — add it. After two or three calibration runs you will know exactly how much to trust each priority level.
Common mistakes
- Treating the Codex review as final. It misses business-logic bugs only a human with context catches. Pre-pass, not verdict.
- Skipping human review entirely. Codex is the cheap first filter, not the decision-maker.
- No
AGENTS.mdreview guidelines. Without them Codex applies generic advice that can contradict your team’s actual choices. - Letting Codex propose and merge fixes unreviewed. Findings and proposed patches are fine; autonomous merges are not.
- Ignoring lint and types because “Codex covers it.” Lint and type checks catch syntax-level issues cheaply; Codex catches convention and logic. Run both.
- Never clearing the backlog. Even with P0/P1-only on GitHub, batch the lower-priority cleanup quarterly or it becomes tech debt.
FAQ
- How long does a Codex review take?: Typically 2-10 minutes for a normal PR, scaling with diff size and how much surrounding code it reasons over.
- What does it cost?: As of June 2026 Codex is bundled with ChatGPT Plus ($20/mo), Pro, and Business ($30/user/mo) — no standalone plan. On April 2, 2026 OpenAI moved Codex from per-message to token-based credits, so heavy review automation draws down credits like API usage.
- Does it replace lint and type checks?: No. Those catch syntax-level issues; the Codex reviewer catches convention and logic issues. Keep both in CI.
- Can it review a draft PR?: Yes, and it often should. Earlier feedback is cheaper than rework after the diff grows.
- Why does it only report P0/P1 on GitHub?: By design, to keep PR threads focused on high-priority risk instead of style nits. Push lower-severity preferences into your
AGENTS.mdguidelines. - What model powers the review?: GPT-5.5-Codex by default; override per-run with
review_modelinconfig.tomlif you want a different model for reviews than for coding.
Related
Tags: #AI coding #Tutorial #Codex