The Forge · 11 min mission
Codex Code Review: The Teammate Who Reads Every Diff
Make Codex review every pull request and only surface the issues that matter.
On this page
Codex code review reads a diff, applies your repo's AGENTS.md review guidelines, and reports prioritized findings without touching your working tree. The same reviewer is exposed through four surfaces — a GitHub PR comment, an AGENTS.md config section, the local /review command, and CI — each with its own trigger, config key, and severity contract.
| Surface | Trigger | Output | Severity | Configured |
|---|---|---|---|---|
| GitHub PR | @codex review comment | Standard GitHub code review | P0 + P1 only | Account-side settings page |
AGENTS.md | ## Review guidelines section | Shapes every review | You define it | Repo file (closest wins) |
Local /review | /review in CLI/app | Findings in the transcript | Prioritized, read-only | review_model in config.toml |
| CI | openai/codex-action@v1 / codex exec | Machine-readable JSON | P0–P3 (no filter) | Workflow file |
Surface 1: @codex review on a pull request
Comment @codex review on a PR. Codex reads the PR diff, follows your repository guidance, and posts a standard GitHub code review — threaded comments in the same place a human teammate would leave them. Scope a single pass with @codex review for <concern> (a one-off steer, not a saved setting). The word review is the switch: @codex followed by anything else starts a cloud task that can push commits, so @codex fix the P1 issue after a review turns a finding into a fix on the branch.
| Comment | Effect |
|---|---|
@codex review | Reviews the diff; posts a standard GitHub review (P0/P1 only) |
@codex review for security regressions, missing tests, and risky behavior changes | Scopes that single review pass to the named concerns |
@codex fix the P1 issue / @codex fix it | Starts a cloud task; can push the fix to the PR branch |
@codex <task> | Any non-review comment starts a cloud task, not a review |
Turn on Codex code review for a repo
Set up Codex cloud for the repository
The GitHub reviewer runs as a Codex cloud task, so the repo must be connected to Codex cloud first. There is no repo-file way to turn the GitHub reviewer on.
Open the code-review settings
Go to
https://chatgpt.com/codex/settings/code-review. Review is enabled per repository here — the toggle lives in ChatGPT, not in your repo.Turn on Code review for the repository
Flip Code review on for the repo. From this point, commenting
@codex reviewon a PR in that repo posts a review.(Optional) Enable Automatic reviews
In the same settings, turn on Automatic reviews: Codex then "post[s] a review whenever someone opens a new PR for review, without needing an
@codex reviewcomment."
Surface 2: shaping reviews with AGENTS.md
Add a ## Review guidelines section to an AGENTS.md file and Codex applies your house rules to every review. The default "P0 = critical / P1 = high" meaning is a convention — guidelines can reassign it (the block below makes typos P0 and missing tests P1). Codex applies the guidance from the closest AGENTS.md to each modified file, so a deep package file overrides the root for changes in its subtree. A separate code_review.md referenced from AGENTS.md keeps the standard identical across repos, and a Security Best Practices skill focuses the review "on risky surfaces such as secrets, auth, and dependency changes."
## Review guidelines
- Flag typos and grammar issues as P0 issues.
- Flag potential missing documentation as P1 issues.
- Flag missing tests as P1 issues.Build the AGENTS.md that drives your reviews
Build your AGENTS.md
Toggle what your repo needs — the file on the right rewrites itself as you click, following the open AGENTS.md format Codex reads: plain Markdown, grouped under ## headings, commands as a table, zero fluff.
Project facts
The first thing the agent reads — say what the repo is in one line.
Stack picks
Naming the stack stops the agent from guessing your toolchain.
Setup commands
Commands save the agent from guessing your scripts. Clear a field to drop it.
Code style
House rules written once here beat repeating them in every prompt.
Testing instructions
Tell the agent when to run tests and when it is allowed to merge.
Security considerations
Fence off the places where an eager edit does damage.
Surface 3: /review in the CLI and app
Type /review in an interactive Codex session (CLI or desktop app) to review changes locally before you push. The reviewer "reads the diff you select and reports prioritized, actionable findings without touching your working tree," and each review is its own turn in the transcript. /review opens a four-option menu, each defined by which diff it inspects.
| Preset | Diff it inspects |
|---|---|
| Review against a base branch | Picks a local branch; finds the merge base against upstream (PR-style read) |
| Review uncommitted changes | Staged, unstaged, and untracked files — before you commit |
| Review a commit | Lists recent commits; analyzes the changeset behind a chosen SHA |
| Custom review instructions | Free-text prompt, e.g. "Focus on accessibility regressions" |
The Codex app wraps the same engine in a review pane showing your Git state with scope switches — Uncommitted changes (default), All branch changes (diff vs base), and Last turn changes — plus a local Unstaged/Staged toggle. Leave inline feedback by hovering a line, clicking the +, and writing a comment; stage or revert at whole-diff, per-file, or per-hunk level.
Choosing the review model with review_model
By default /review uses your current session model. Set review_model in config.toml (~/.codex/config.toml global, or repo-scoped .codex/config.toml) to use a different model for reviews only. It is a single string — an "optional model override used by /review (defaults to the current session model)." As of 2026-06-15 the lineup is gpt-5.5 (recommended default — "For most tasks in Codex, start with gpt-5.5"), gpt-5.4, gpt-5.4-mini, and the research-preview gpt-5.3-codex-spark; gpt-5.2 and gpt-5.3-codex are deprecated in Codex when you sign in with ChatGPT.
# Optional. Affects ONLY the local /review slash command.
# It does not configure the GitHub PR reviewer or a headless CI run.
review_model = "gpt-5.5"Surface 4: review in CI
For review on every PR with no human typing @codex review, use the building blocks underneath the other surfaces. The openai/codex-action@v1 GitHub Action installs the Codex CLI, starts the Responses API proxy with your OpenAI key, and runs codex exec under the permissions you specify; you feed it a prompt or prompt-file and it returns a final-message output. The portable primitive it wraps is codex exec --output-schema with --sandbox read-only, which emits machine-readable JSON findings instead of prose — the cookbook ships this same shape for GitHub Actions, GitLab CI/CD, Azure DevOps, and Jenkins.
| Input | Default | What it does |
|---|---|---|
openai-api-key | "" | API key used to start the Responses API proxy |
prompt / prompt-file | "" | Inline prompt, or a committed prompt file |
output-file | "" | Where the final message is written |
sandbox | workspace-write | Effective default; use read-only for a pure reviewer |
safety-strategy | drop-sudo | Removes sudo before the agent runs (Windows: only unsafe) |
model / effort | "" | Override the model and reasoning effort for the run |
allow-users | "" | Gates who can trigger the workflow |
name: Codex pull request review
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
codex:
runs-on: ubuntu-latest
permissions:
contents: read # the review job holds NO write scopes
outputs:
final_message: ${{ steps.run_codex.outputs.final-message }}
steps:
- uses: actions/checkout@v5 # must run before Codex: it needs the repo on disk
- 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
post_feedback:
needs: codex
runs-on: ubuntu-latest
permissions:
issues: write # write scopes live ONLY in the posting job
pull-requests: write
steps:
- uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `${{ needs.codex.outputs.final_message }}`
})# The portable core every CI target wraps. --output-schema makes Codex
# return JSON findings instead of prose; --sandbox read-only guarantees no edits.
codex exec --output-schema codex-output-schema.json \
--output-last-message codex-output.json \
--sandbox read-only \
- < codex-prompt.md| Field | Shape | What it carries |
|---|---|---|
findings[] | array | One entry per issue Codex raises |
title / body | string | Short headline (maxLength 80) and full explanation of a finding |
priority | integer 0–3 | P0–P3 — the schema keeps all four levels, unlike the GitHub surface |
confidence_score | number 0–1 | How sure Codex is about that finding |
code_location | object | absolute_file_path plus line_range.{start,end} |
overall_correctness | enum | "patch is correct" or "patch is incorrect" for the whole diff |
Knowledge check
You enable "Automatic reviews" and comment `@codex review for security regressions` on a PR. A teammate asks why a known low-severity style nit Codex usually mentions did not appear in the GitHub review. What is the correct explanation?
Reach the end and this star joins your charted sky.