Codex Code Review (/review): A Walkthrough With Example
/review is Codex's (OpenAI Codex CLI) dedicated diff reviewer: it never edits files in your working tree, it only reads and returns a prioritized findings list. You can run it from CLI, an IDE extension, the ChatGPT desktop app, or ChatGPT web, with 4 presets depending on what scope you want reviewed. This walkthrough covers the mechanics: the 4 presets, the non-interactive CLI flags for scripts/CI, a real reviewed-diff example, and when you actually need gh to read a GitHub PR.
- Codex is a fast-moving feature surface; the details below were cross-checked against the official docs at the time of writing (08/2026) - verify live docs before depending on an exact flag name or behavior.
What /review actually does
/review runs a separate, read-only sub-turn: it reads the diff you point it at and never touches files in your working tree. The output is a prioritized findings list tied to positions in the diff, not a generic paragraph of comments. That is the key difference from pasting a diff into chat and asking "does this look okay" - /review is a distinct, structured flow, separate from your active coding session.
Per the official docs (learn.chatgpt.com/docs/code-review, accessed 08/2026), it's built to run before opening a PR or before merging - not a "fix it for me" mode like a normal Codex task. If you're used to Claude Code's review flow, the mental model carries over: a separate step, read-before-write.
The 4 review presets
Codex doesn't have one generic "review" button - you pick a preset based on the diff scope you want reviewed:
| Preset | When to use it | What it reviews |
|---|---|---|
| Base branch | Finished a branch, want the whole thing reviewed before opening a PR | Codex finds the merge base, then reviews the branch diff against it |
| Uncommitted | Mid-edit, haven't run git add yet, want an early check | Staged + unstaged + untracked changes |
| A commit | Need to review one specific commit, e.g. before a rebase/squash | That exact commit's change set, nothing else |
| Custom instructions | You have your own criteria, e.g. security-only or an internal coding standard | Freeform - you describe the criteria, Codex reviews against exactly that |
In the composer, type /review and pick a preset from the menu. The first three are "pick an existing diff scope"; the fourth is where you write your own criteria when the default scope isn't enough - e.g. "only flag auth vulnerabilities" or "review against the coding standard in AGENTS.md".
Where you can run it - CLI, IDE, app, web
/review isn't locked to one surface. Four surfaces currently support it:
- CLI - type
/reviewin the composer during a terminal session, or run the non-interactivecodex reviewcommand from a script/CI (see the flags section below). - IDE extension - the same composer, embedded in VS Code/JetBrains, reviewing right next to the diff you have open, no window switch needed.
- ChatGPT desktop app - has a dedicated review pane, useful when you want the review window separate from your coding window.
- ChatGPT web - run a review straight from the browser, handy when you don't have your dev machine on hand.
All four surfaces share the same underlying review mechanism, but the exact UI and naming on each surface isn't guaranteed to match 1:1 - worth verifying live docs if a button name or menu location in this article looks off.
The non-interactive CLI flags (for scripts/CI)
Besides /review in the composer, Codex ships a non-interactive codex review command, built for scripts or a CI pipeline. Per learn.chatgpt.com/docs/cli/reference, accessed 08/2026:
# Review the diff against a base branch
codex review --base main
# Review one specific commit, with an optional title (--title requires --commit)
codex review --commit <sha> --title "Fix invoice endpoint"
# Review uncommitted changes (staged + unstaged + untracked)
codex review --uncommitted
# Freeform prompt, read directly from stdin
git diff | codex review -
# Strict-match config.toml when you need consistent CI behavior
codex review --base main --strict-configKey rule: the scope flags are mutually exclusive - pick exactly one of --base, --commit, --uncommitted, or a PROMPT/stdin per run, never mix them. This is a common place for silent renames across Codex releases, so re-check the exact flag names before hardcoding them into CI.
Reviewing a real diff - a worked example
Theory aside, here's the kind of finding /review tends to catch on a small Node.js route (trimmed for illustration, not a verbatim raw output). The route fetches an invoice by ID in a multi-tenant system:
// Before
async function getInvoice(req, res) {
const invoice = await db.invoices.findOne({ id: req.params.id });
if (!invoice) return res.status(404).end();
res.json(invoice);
}Finding 1 (severity: high, correct): "Missing tenant-scope filter - the route only queries by id, so a user on tenant A can view tenant B's invoice by guessing the ID. Add tenantId: req.user.tenantId to the query filter." This is a textbook IDOR (insecure direct object reference) bug - syntactically fine, runs without errors, but leaks data across tenants. The fix:
// After
async function getInvoice(req, res) {
const invoice = await db.invoices.findOne({
id: req.params.id,
tenantId: req.user.tenantId,
});
if (!invoice) return res.status(404).end();
res.json(invoice);
}Finding 2 (severity: medium, needed a human second look): /review also flagged "this route has no rate limiting." That's correct at the code level - but after checking gateway.config.ts, the route already sits behind the API gateway's global rate limiter. The finding wasn't technically wrong, it was just missing context /review can't see (config outside the diff's scope) - a case where a human needs to confirm before acting on it, not apply it automatically.
Two findings in one run demonstrate exactly how to read /review output: finding 1 is a real bug, fix it now; finding 2 is locally correct but missing system context - it needs your confirmation, not an automatic apply.
Reviewing a GitHub PR - what needs gh
Two distinct GitHub mechanisms are easy to conflate if you skim:
1. Reading PR context locally (needs gh). When you review a PR from CLI, app, or IDE, Codex needs gh installed and authenticated to pull PR info (title, description, comments). Per the docs: if gh is missing or unauthenticated, PR details may not appear in the sidebar or review pane. Setup is one command:
gh auth login2. Triggering a cloud review via comment (no local gh needed). Commenting @codex review directly on a GitHub PR triggers a review that runs cloud-side - a completely separate mechanism from local PR-context reading above, and it doesn't require gh on your machine. The condition is that Codex cloud is already configured for your repo. This mechanism belongs to the deeper Codex Cloud setup - if you want to configure this kind of automated review trigger, that lives in the Codex Cloud guide; this is just one line so you don't conflate the two mechanisms.
How much should you trust a /review finding?
To be direct: a /review finding is a prioritized suggestion, not an automatic merge gate. Finding 2 above makes that plain - syntactically correct, locally correct logic, but wrong because it's missing system context. That kind of false positive happens more often than you'd expect when a review only sees the diff, not the whole repo.
So a human (or, if you've installed AgentKit's Engineer Kit, its code-review skill/agent) still gates the actual merge decision - /review just shortens the mechanical-scanning part so the human reviewer can spend effort on the harder part. AgentKit ships a /ak:review command with a similar review flow that runs in both Claude Code and Codex, handy if you want a prebuilt process instead of assembling one; but to be clear, that's a paid kit layered on top - Codex's own /review is already free and enough for individual review. If you haven't set it up, see using AgentKit inside Codex first.
Want a dedicated review agent running alongside Codex's /review? AgentKit's Engineer Kit ships a code-review skill/agent via /ak:review, working on both Codex and Claude Code - it doesn't replace /review, it adds a preconfigured extra layer.
Codex /review vs Claude Code's review flow
Same idea, different tool. Claude Code has its own /review with the same "block merge while a serious finding remains" workflow - the 3-step process and a real finding example live in the AI code review guide for Claude Code (that article never mentions Codex, and this one doesn't repeat its content). If you run both tools, the underlying principle holds either way: review on the diff, rank by severity, and a human still makes the final merge call.
Frequently asked questions
What are Codex's /review presets?
Base branch (reviews the whole diff against the merge base), Uncommitted (staged + unstaged + untracked), A commit (that exact commit's change set), and Custom instructions (you describe your own review criteria, freeform).
Does /review edit my code?
No. /review runs a read-only sub-turn and never touches files in your working tree. It only returns a prioritized findings list - you decide what to fix or skip.
Do I need gh for PR reviews?
Yes, for reading PR context locally (title, description, comments) from CLI/app/IDE - gh must be installed and authenticated, or PR details may not appear in the sidebar. That's different from commenting @codex review, which doesn't need local gh.
What's @codex review on GitHub?
A way to trigger a cloud-side review by commenting @codex review directly on a PR, separate from reading PR context locally. It requires Codex cloud already configured for your repo; the deeper details belong to Codex Cloud, not this article's scope.
Can I run reviews from a script/CI?
Yes, via the non-interactive codex review command with --base, --commit, --uncommitted, or a PROMPT/stdin - exactly one scope flag per run, never combined.
Does /review replace a human approval?
No. A /review finding is a prioritized suggestion that can be wrong for missing system context (see finding 2 above). A human - or a dedicated review agent like AgentKit's Engineer Kit ships - still makes the final merge call.
Conclusion
In short: Codex's /review has 4 presets, runs on CLI/IDE/app/web, never edits files on its own, and needs gh when you want local PR context - while @codex review as a comment is a separate cloud mechanism. Read findings as prioritized suggestions, not an automatic merge gate. If you also run Claude Code, see the AI code review flow for Claude Code; if you're new to Codex, start with what OpenAI Codex is.