Codex code review: the local command, @codex review, and the Action

Codex has three ways to review code, plus a fourth thing named auto-review that is not code review at all. What codex review and codex exec review actually take, what the bundled review-agent skill defines as a finding, why GitHub reviews only post P0 and P1, how AGENTS.md review rules work, and the Action's prompt injection warning.

"Codex code review" can mean three different things, and searches for "codex auto-review" usually mean a fourth thing that does not review code at all. It is worth sorting out which one you want before configuring any of them:

1. codex review in your terminal, for local changes.
2. @codex review on a GitHub pull request, or automatic reviews on every PR.
3. The Codex GitHub Action, for a review job you define yourself.
4. Auto-review, which reviews approval requests during a session, not your diff.

We checked the CLI side against Codex CLI 0.147.0 and read the review skill it ships. The GitHub side is covered from OpenAI's documentation. If you use Claude Code as well, it has the same kind of naming overlap, which we covered in its version of this post.

1. codex review, the local one

codex review --uncommitted
codex review --base main
codex review --commit a1b2c3d

Those three flags pick the target:

• --uncommitted reviews staged, unstaged, and untracked changes. A new file you have not added to git yet still gets reviewed.
• --base <branch> reviews your branch against a base branch.
• --commit <sha> reviews what one commit introduced. --title sets the commit title shown in the review summary.

A positional argument adds your own instructions. Pass - to read them from stdin:

codex review --base main "Focus on the retry logic in src/queue and ignore formatting."

For scripts, the same review is available as codex exec review, with the same target flags. The scripting options are covered in the section on automating it, below.

What Codex counts as a finding

Codex ships a system skill called review-agent, installed under ~/.codex/skills/.system. It is written for the case where one agent hands a review to another, and it is the clearest statement Codex gives of what a good review looks like. It is worth reading even if you never call it.

The skill flags an issue only when all of these are true:

• It affects correctness, security, performance, or maintainability in a meaningful way.
• It is discrete and actionable.
• It was introduced by the reviewed change.
• The affected scenario or call path can be demonstrated from the code.
• The author would probably fix it if they knew about it.

It also explicitly excludes speculative concerns, pre-existing problems, intentional behavior changes, and style nits.

Findings use four priority levels:

• P0: a release blocker or critical failure.
• P1: an urgent defect to fix next.
• P2: an ordinary defect.
• P3: low impact, but still worth fixing.

If nothing qualifies, the expected output is No findings., and the skill says not to invent one to fill the result.

One detail matters for branch reviews. The skill compares against the merge base, using git merge-base HEAD <ref>, rather than the tip of the base branch. That way the review covers only the changes that would actually merge, not everything that has landed on main since you branched.

The skill sets allow_implicit_invocation: false, so Codex never loads it on its own. To use it you name it explicitly, as $review-agent. This is the explicit-only pattern described in the Codex skills post.

2. @codex review on GitHub

This path needs Codex cloud set up for the repository, and code review enabled in its settings. After that there are two ways to trigger a review:

• Manual: comment @codex review on a pull request. Codex reacts with 👀, then posts its findings as a normal GitHub review with inline comments.
• Automatic: turn it on in settings, and Codex reviews every new pull request without being mentioned.

Per the docs, the GitHub review posts only P0 and P1 issues. That is a deliberate trade-off: comments stay rare enough that people actually read them. It also means P2 and P3 issues never appear on the PR. If you want those, run codex review locally before you push.

A separate security pass is in research preview. You request it with @codex security review.

Teaching it your rules through AGENTS.md

Both the GitHub review and the local reviewer read AGENTS.md. To give reviews repository-specific guidance, add a section with this exact heading:

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

Rules are scoped by location. Codex applies the root AGENTS.md plus the file closest to the code that changed. So repository-wide rules go at the root, and rules for one service go in that service's directory.

OpenAI's guidance on writing these rules comes down to four points:

• Start with an invariant that matters and that reviewers keep having to explain.
• Scope each rule to the code it governs.
• State both the risk and the safe way to do it.
• Leave out anything CI already checks mechanically.

Their example of a good rule is precise: "Do not filter treatment comparisons on post-exposure behavior, including conversion or retention." A rule like "write clean code" gives the reviewer nothing to act on.

If you already maintain AGENTS.md for other tools, the same file serves all of them. The AGENTS.md comparison covers how Claude Code reads, and does not read, that file.

3. The GitHub Action

When you want to control the review job yourself, use openai/codex-action@v1:

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

Three details in that example are deliberate:

• persist-credentials: false keeps the GitHub token out of the working copy that Codex can read.
• permissions: contents: read keeps the job read-only.
• safety-strategy defaults to drop-sudo, which removes sudo privileges. Windows runners need safety-strategy: unsafe, which is a strong reason to run this job on Linux.

The docs include two warnings that should be taken literally. First, do not rely on a read-only sandbox alone to protect secrets. Second, sanitize anything taken from pull requests, commit messages, or issue bodies before it reaches the prompt, because that text is written by whoever opened the PR. A review job on a public repository is processing input from strangers. This is the same threat model as the Claude Code security post, and it matters even more when the job has repository access.

4. Auto-review, which is not code review

People searching "codex auto-review" are usually looking for this setting:

approvals_reviewer = "auto_review"

It routes approval requests during a session through an automatic reviewer, instead of asking you each time. It does not review your code. The CLI has a flag for the same behavior, and its help text describes it exactly:

--approve-for-me
    Route approval requests through automatic review using the workspace-write sandbox

It belongs with sandbox and approval settings, not with code review. It is closer to Claude Code's auto mode than to anything in this post.

Automating a local review

codex exec has the options that make a review usable in a pipeline:

codex exec review --base main \
  --ephemeral \
  --ignore-user-config \
  -o review.md

• --ephemeral skips writing session files to disk.
• --ignore-user-config skips your ~/.codex/config.toml, so the review behaves the same on every machine. Authentication still comes from CODEX_HOME.
• -o / --output-last-message writes the final review to a file.
• --json prints the event stream as JSONL.
• On plain codex exec, --output-schema <file> constrains the final response to a JSON Schema. That is the way to get findings you can parse reliably instead of scraping markdown.

One flag should stay out of review jobs: --dangerously-bypass-hook-trust. It runs enabled hooks without the per-hook trust step, and its own help text says it is intended only for automation that already vets hook sources. A job that checks out someone else's pull request is not that.

Which to use

• Before you push: codex review --uncommitted, or --base main. It is fast, local, and reports all four priority levels.
• On every PR, with no setup to maintain: automatic reviews through Codex cloud. You get only P0 and P1, which is usually the right amount of noise for a team.
• When you need custom triggers or custom prompts: the Action, pinned to @v1, running on Linux, with sanitized inputs.
• In every case: put the rules you keep repeating in ## Code Review Rules, next to the code they apply to.

The pattern that holds across all three is to review before the PR exists rather than after. A finding you fix in your working tree costs one edit. The same finding raised as a PR comment costs a round trip and a teammate's attention.