codex-review

name	codex-review
description	Codex code review closeout: local dirty changes, PR branch vs main, parallel tests.

Codex Review

Run Codex's built-in code review as a closeout check. This is code review (codex review), not Guardian auto_review approval routing.

Use when:

• user asks for Codex review / autoreview / second-model review
• after non-trivial code edits, before final/commit/ship
• reviewing a local branch or PR branch after fixes

Contract

• Treat review output as advisory. Never blindly apply it.
• Verify every finding by reading the real code path and adjacent files.
• Read dependency docs/source/types when the finding depends on external behavior.
• Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase.
• Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class.
• Keep going until Codex review returns no accepted/actionable findings.
• If a review-triggered fix changes code, rerun focused tests and rerun Codex review.
• If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
• Do not push just to review. Push only when the user requested push/ship/PR update.

Pick Target

Dirty local work:

codex review --uncommitted

Branch/PR work:

git fetch origin
codex review --base origin/main

Do not pass an inline prompt with --base; current CLI rejects --base + [PROMPT] even though help text is ambiguous. If custom instructions are needed, run the plain base review first, then do a local/manual follow-up pass.

If an open PR exists, use its actual base:

base=$(gh pr view --json baseRefName --jq .baseRefName)
codex review --base "origin/$base"

Committed single change:

codex review --commit HEAD

Parallel Closeout

Format first if formatting can change line locations. Then it is OK to run tests and review in parallel:

scripts/codex-review --parallel-tests "<focused test command>"

Tradeoff: tests may force code changes that stale the review. If tests or review lead to code edits, rerun the affected tests and rerun review until no accepted/actionable findings remain.

Context Efficiency

Codex review is usually noisy. Default to a subagent filter when subagents are available. Ask it to run the review and return only:

• actionable findings it accepts
• findings it rejects, with one-line reason
• exact files/tests to rerun

Run inline only for tiny changes or when subagents are unavailable.

Helper

Bundled helper:

~/.codex/skills/codex-review/scripts/codex-review --help

If installed from agent-scripts, path is:

/Users/steipete/Projects/agent-scripts/skills/codex-review/scripts/codex-review --help

The helper:

• chooses dirty --uncommitted first
• otherwise uses current PR base if gh pr view works
• otherwise uses origin/main for non-main branches
• writes only to stdout unless --output or CODEX_REVIEW_OUTPUT is set
• supports --dry-run and --parallel-tests

Final Report

Include:

• review command used
• tests/proof run
• findings accepted/rejected, briefly why
• final clean review command, or why a remaining finding was consciously rejected