Reviewing Pull Requests with OpenAI Codex
Codex code review means pointing the Codex CLI or its GitHub integration at a diff and getting back structured comments on bugs, security issues, and style violations before a human reviewer even opens the PR. You can run it locally against an uncommitted branch, wire it into GitHub so it comments automatically on every pull request, or invoke it on demand with a slash command inside an existing PR thread. This guide covers the setup, the exact commands, how to write a review prompt Codex actually follows, and where it still needs a human backstop.
Why Add Codex to Your Pull Request Workflow
Most teams already run linters and type checkers in CI. Those catch syntax problems and style drift, but they do not understand intent. They will not tell you that a retry loop has no backoff, that a new database query runs inside a hot path without an index, or that an error is being swallowed instead of logged. That is the gap Codex code review fills: it reads the diff the way a careful engineer would, with the context of the surrounding files, and writes comments a human reviewer can act on directly.
The other reason to add it is speed. A first pass from Codex on a large PR means the human reviewer opens it already knowing where the risky lines are, instead of reading every file cold. On a team with a small number of senior reviewers, that first pass is often the difference between same-day review and a two-day queue.
None of this replaces a human sign-off. Codex code review is a filter, not a gate. Treat its output the same way you would treat a junior engineer's first-pass comments: useful signal, but the merge decision stays with a person.
Installing and Authenticating Codex CLI
Codex ships as a CLI you install with your Node package manager, and it authenticates either with your ChatGPT account or with an API key, depending on how your organization has it set up.
npm install -g @openai/codex
codex loginRunning codex login opens a browser flow for account-based auth. If your org uses API-key auth instead, set the key as an environment variable before running any Codex command:
export OPENAI_API_KEY="sk-..."
codex login --api-keyVerify the install and check which account or key Codex is using:
codex --version
codex whoamiRun this from inside the repository you want to review, not from your home directory. Codex CLI infers project context (language, package manager, existing config files) from the current working directory, and that context feeds directly into the quality of its review.
Configuring Codex for Your Repository
Codex reads a project-level config file, AGENTS.md, placed at the root of the repo. This is where you tell it what "good" looks like for your codebase: naming conventions, patterns to avoid, which directories are generated and should be skipped, and any house rules a generic review would miss.
A minimal example for a TypeScript backend:
# AGENTS.md
## Code review rules
- Flag any `any` type in TypeScript without a comment explaining why.
- Flag database queries inside loops (N+1 risk).
- All new API routes must have input validation via zod.
- Ignore files under generated/ and dist/, they are build output.
- Error handling: never catch an error without logging or rethrowing it.
- Prefer named exports over default exports.Keep this file short and specific. A long list of vague preferences produces vague reviews. A short list of concrete, checkable rules produces comments you can act on without arguing about taste.
You can also scope config per directory. Dropping a second AGENTS.md inside apps/api/ lets you layer stricter rules for that subtree (say, stricter handling of PII) on top of the repo-wide rules, without touching the root file.
Running a Codex Review from the Command Line
The most direct way to review a pull request is to check out the branch locally and point Codex at the diff against your base branch.
git fetch origin
git checkout feature/rate-limit-retries
codex review --base mainThis diffs the current branch against main, sends the changed files (plus enough surrounding context for Codex to understand call sites) to the model, and prints a structured review to your terminal: file, line, severity, and a one-line explanation of the issue.
If you want the review as a file you can paste into the PR description or share with a teammate, redirect it to markdown:
codex review --base main --format markdown > review.mdFor a review of a specific commit range instead of a branch comparison, pass the range directly:
codex review --diff HEAD~3..HEADYou can also run Codex non-interactively as part of a local pre-push check, so problems surface before you even open the PR:
codex exec "review the diff against main for security issues and unhandled errors only" --base mainThe codex exec form takes a one-off natural-language instruction instead of the general review preset, which is useful when you want a narrow pass (only security, only performance, only test coverage) rather than the full checklist.
Automating Codex Review on Every Pull Request
Running Codex by hand works for solo checks, but the real value shows up when it comments automatically on every PR without anyone remembering to trigger it. Set this up with a GitHub Actions workflow that runs on pull_request events.
# .github/workflows/codex-review.yml
name: Codex Review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install Codex CLI
run: npm install -g @openai/codex
- name: Run Codex review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex review \
--base "${{ github.event.pull_request.base.ref }}" \
--format github-comment \
--output review-comment.md
- name: Post review as PR comment
uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('review-comment.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body,
});Store the API key as a repository secret (Settings > Secrets and variables > Actions), never in the workflow file itself. fetch-depth: 0 matters here: Codex needs the full git history to compute an accurate diff against the base branch, and a shallow checkout will either fail or silently review the wrong range.
On synchronize events (a new push to an existing PR), this workflow reruns automatically, so the review comment updates with every push rather than going stale after the first commit.
If your team uses a GitHub App-based Codex integration instead of a raw CLI call in Actions, the setup differs: you install the app from your GitHub organization settings, grant it access to the specific repositories, and it listens for PR events on its own infrastructure. That route needs less workflow YAML but gives you less control over exactly which checks run and when. Pick the Actions route above when you want the review rules under version control alongside the code they review; pick the app route when you want zero maintenance and are fine with the default review behavior.
Triggering Codex from a Pull Request Comment
Beyond the automatic pass, most teams also want an on-demand trigger, useful when a reviewer wants a second opinion mid-review or wants Codex to re-check after requesting changes. Add a second workflow that listens for a comment command:
# .github/workflows/codex-review-comment.yml
name: Codex Review on Demand
on:
issue_comment:
types: [created]
jobs:
review:
if: github.event.issue.pull_request && contains(github.event.comment.body, '/codex-review')
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
ref: refs/pull/${{ github.event.issue.number }}/head
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g @openai/codex
- name: Run Codex review
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
run: |
codex review --base main --format github-comment --output review-comment.md
- uses: actions/github-script@v7
with:
script: |
const fs = require('fs');
const body = fs.readFileSync('review-comment.md', 'utf8');
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body,
});Now anyone with write access can comment /codex-review on a PR and get a fresh pass, which is especially useful after a round of fixes when you want to confirm the flagged issues are actually resolved rather than re-reading the whole diff yourself.
Writing Review Prompts Codex Will Actually Follow
The default codex review preset does a broad pass: correctness, security, obvious performance issues, and test coverage gaps. That is a reasonable default, but narrow prompts produce sharper output. Compare a vague instruction to a specific one.
Vague, produces generic comments:
codex exec "review this PR"Specific, produces comments you can act on immediately:
codex exec "review the diff against main. Only flag: (1) SQL queries built with string concatenation instead of parameterized queries, (2) any new environment variable read without a default or validation, (3) API endpoints missing rate limiting. Skip style and formatting entirely." --base mainThe pattern that works well across teams: keep the default full-checklist run for the automatic PR comment, and reserve narrow, single-purpose prompts for the on-demand /codex-review trigger when a reviewer already has a specific concern (a security-sensitive change, a hot-path performance change, a migration).
For consistently good output, also point Codex at your test files and existing patterns rather than asking it to judge in a vacuum:
codex exec "review the diff. For each new function, check whether an equivalent existing utility already exists in src/lib/ before flagging missing abstraction. Compare error handling style against src/lib/errors.ts." --base mainThis cuts down on a common failure mode: a review tool suggesting a new helper function that duplicates one that already exists three files away.
Reading and Triaging Codex's Comments
A Codex review comment typically has three parts: the file and line, a severity label, and a short explanation with a suggested fix. Treat severity as a sorting hint, not gospel. In practice:
- Comments about unvalidated input, missing auth checks, or hardcoded secrets deserve an immediate look regardless of how the label reads.
- Comments about naming, ordering of imports, or minor style preferences are safe to skip unless they trip a linter rule your team actually enforces.
- Comments suggesting a broader refactor ("this class is doing too much") are worth a skim but rarely worth blocking a PR over. Note them for a follow-up ticket instead of expanding the current diff.
Watch for two specific failure modes. First, false positives on code that looks risky out of context but is actually safe because of validation upstream, for example a query that looks unparameterized but is passed through an ORM that parameterizes it under the hood. Codex sees the diff plus surrounding files, not always the full call graph, so give it the benefit of the doubt only after checking, not before. Second, stale comments after a fix: if you push a follow-up commit addressing a flagged issue, rerun the review (via /codex-review or the automatic synchronize trigger) rather than assuming the original comment still applies.
Codex Review vs Human Review: Where the Line Sits
Codex is strong at pattern matching against known bug classes: unhandled promise rejections, missing null checks, SQL injection shapes, N+1 queries, secrets in code, and inconsistent error handling. It is weak at judging whether a change is the right change for the product, whether the abstraction fits how the team will extend this code in six months, and whether a shortcut is an acceptable tradeoff given a deadline the model has no visibility into.
A workable split for most teams:
- Codex runs automatically on every PR and handles the mechanical pass: bugs, security, obvious performance issues, test coverage gaps.
- The human reviewer reads Codex's comments first, dismisses the noise, and confirms or overrides the real findings.
- The human reviewer then spends their remaining attention on the things Codex cannot judge: architecture fit, whether the PR does the right thing, and whether the tradeoffs match the team's actual priorities.
This ordering matters. If the human reads the diff cold and Codex's comments second, they end up re-deriving everything Codex already found. Reading Codex's pass first, then the diff, is faster and catches more, because the reviewer's attention goes straight to the parts a tool cannot judge.
Common Pitfalls
Running Codex review without an AGENTS.md file produces reviews that read like a generic linter with opinions, useful but not tuned to your codebase. Write the config file before you judge whether the reviews are actually good.
Running the CLI with a shallow git checkout (--depth 1 or CI default checkout without fetch-depth: 0) causes diff computation to fail or, worse, silently diff against the wrong commit. Always fetch full history in CI before calling codex review.
Treating every comment as a blocker slows the team down and trains people to stop reading the comments at all. Set an explicit team norm, for example: security and correctness comments block merge, everything else is optional, and enforce it consistently so the tool's credibility does not erode.
Skipping the human pass entirely because "Codex already reviewed it" is the biggest risk. Codex code review reduces the human reviewer's workload; it does not replace the judgment call about whether a PR should merge.
FAQ
Does Codex review replace a human code reviewer? No. It is a first pass that catches mechanical issues (bugs, security patterns, missing tests) fast, so the human reviewer spends their time on architecture and product fit instead of re-deriving the same bugs a tool could have caught. Merge approval should stay a human decision.
Can Codex review a PR without seeing the whole repository? It works best with repository access because it needs surrounding context (existing utilities, call sites, conventions) to avoid false positives. A diff-only review without repo context is possible but produces noisier, more generic comments.
How do I stop Codex from commenting on generated or vendored files? List those paths under an ignore rule in AGENTS.md, and also exclude them at the git level if they are not already in .gitignore. Codex respects repo-level ignore configuration when computing the diff to review.
Can I run Codex review only on specific file types, like just backend code? Yes, scope it with a path filter in the review command or by structuring AGENTS.md rules under directory-specific sections so only relevant paths get certain checks.
What happens if Codex and a human reviewer disagree on a finding? The human reviewer's judgment wins. Codex review comments are advisory. If a comment is consistently wrong for your codebase's patterns, that is a signal to tighten the AGENTS.md rules or narrow the review prompt rather than ignore the tool going forward.
Does automatic PR commenting on every push get noisy? It can, if the workflow reposts a full comment on every synchronize event. Mitigate this by having the script edit the existing Codex comment in place (using the GitHub API to find and update a prior comment by the bot) instead of posting a new one each time.
Is Codex review slower than just reading the diff myself for a small PR? For a small, low-risk PR, probably yes; the setup and API round-trip can cost more time than a two-minute manual read. The value shows up on larger PRs, on PRs touching unfamiliar parts of the codebase, and on repositories where review capacity is the actual bottleneck.
AI CodingShip full-stack AI apps at conversation speed — specs, agents, deploys, all from the terminal.
CodexLearn to drive OpenAI's coding agent: real tasks, safe sandboxing, and terminal-to-cloud workflows that ship.