| name | codex-review |
| description | Run OpenAI Codex's AI code review LOCALLY via the `codex` CLI BEFORE opening a PR (part of pre-PR self-review). Runs one-shot, reviewing the current branch against main, prints findings to stdout, and you resolve them before the PR is opened. Use during pre-PR self-review, alongside fx-dev:coderabbit-review. |
Codex Review
This skill runs OpenAI Codex's AI code review locally, one-shot, against the
current branch. Run it as part of pre-PR self-review — after coderabbit-review,
before opening the PR — fix everything it finds, and only then open the PR.
It complements (does not replace) coderabbit-review: CodeRabbit and Codex are
independent reviewers and each catches issues the other misses.
Project Conventions
Codex reads AGENTS.md — it does not read REVIEW.md or CLAUDE.md. Every
other reviewer reaches REVIEW.md on its own; Codex is the exception. The bridge
is a ## Code Review Rules section in AGENTS.md pointing at REVIEW.md, which
the fx-dev:setup skill creates.
Before the first run in a repo, check the pointer exists:
grep -q "## Code Review Rules" AGENTS.md 2>/dev/null \
&& echo "Codex pointer present" \
|| echo "MISSING - run fx-dev:setup (new repo) or fx-dev:upgrade (legacy layout)"
If it is missing, report it and continue reviewing on defaults — do NOT run
fx-dev:setup or fx-dev:upgrade from here. Setup scaffolds docs/ and touches
CodeRabbit config, and upgrade rewrites instruction files outright; running
either mid-review would pollute the branch with changes unrelated to the PR.
Tell the user to run it separately.
If Codex flags something that REVIEW.md explicitly permits, the pointer is not
landing — say so rather than silently applying the finding.
How to Run (one-shot, branch vs main)
Codex has a dedicated non-interactive review subcommand. From the repo root, on
your working branch:
codex review --base main
This picks the current branch, diffs it against main, and prints the review
(highest-risk findings first) to stdout — no interactive session, no edits to
your tree (review is read-only).
Useful variants:
- Capture to a file for later reference (redirect stdout):
codex review --base main | tee /tmp/codex-review.md
- Custom focus: append a prompt, e.g.
codex review --base main "Focus on security and data-loss risks"
- Uncommitted-only (staged + unstaged + untracked):
codex review --uncommitted
(Run codex review --help for the exact flags your CLI version supports — there is no dedicated --json/-o flag, so use shell redirection to capture output.)
Notes:
- Prefer
--base main so the review scope matches what the PR will contain.
Use --uncommitted only when changes aren't committed yet.
- If the workspace is externally sandboxed and Codex prompts for approvals in a
non-interactive context, add
--dangerously-bypass-approvals-and-sandbox
(review is read-only, so this is safe here). Try without it first.
- Requires the
codex CLI to be installed and already authenticated. The workspace is expected to be authed; if it is not, STOP and report to the user — do NOT run codex login (it is interactive).
Workflow (fix → re-run → converge)
Treat Codex's findings like self-review feedback and loop until the review is clean.
Step 1: Run the review
codex review --base main
Use --uncommitted instead of --base main for not-yet-committed work. If the
codex CLI is unavailable or not authenticated, report to the user once and
skip this pass — NEVER run codex login (it is interactive; the workspace is
expected to be authed already).
Step 2: Resolve every actionable finding
- Fix real issues in code and tests; make atomic commits for the fixes.
- Nitpicks may be applied or consciously skipped — don't churn on style the
project doesn't care about. There are no PR threads to resolve here (this is
local); resolution = the code is fixed (or the finding is a deliberate
non-issue).
- Incorrect findings — when Codex flags a pattern that is a deliberate project
convention, document it in
REVIEW.md at the repo root, the same as the PR
feedback resolvers do. One entry stops Codex, Copilot, CodeRabbit, and Claude
Code Review from raising it again. Never write it into
the obsolete .github/copilot-instructions.md.
Step 3: Re-run until clean (REQUIRED)
Run codex review --base main again after fixes. Repeat Steps 1 → 2 until
the review reports no actionable findings.
- Cap at 4 iterations. If Codex keeps flagging the same design decision after
4 passes, that is a human call, not more code edits — escalate to the user.
Step 4: Open the PR only when clean
A clean Codex review (alongside a clean CodeRabbit review) is the gate to PR
creation in the SDLC (fx-dev:dev Step 4.5 → Step 5). Do not open the PR with
unresolved actionable Codex findings.
When to Use This Skill
- Pre-PR self-review: run after
coderabbit-review and before pr-preparer.
Both reviewers must come back clean before the PR is opened.
Notes
- This skill is self-contained: it does not load other skills, and it never runs
fx-dev:setup or fx-dev:upgrade — a missing AGENTS.md pointer is reported,
not fixed here.
codex review reviews local changes and never modifies your working tree.- Keep findings resolved before opening the PR.
