| 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.
- Never switch or override the review model. If the review hits model capacity, retry the same command a few times with the same model. If it hits sandbox/permission limits, use the helper's
--full-access option instead of changing models.
- Stop as soon as the review command/helper exits 0 with no accepted/actionable findings. Do not run an extra direct
codex review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
- Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
- 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
Use this only when the patch is actually unstaged/staged/untracked in the
current checkout. For committed, pushed, or PR work, review the branch against
its base instead; do not force --mode local / --uncommitted just because the
helper docs mention dirty work first. A clean --uncommitted review only proves
there is no local patch.
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:
~/.codex/skills/codex-review/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. Once that rerun exits cleanly, stop; do not spend another long review cycle on redundant confirmation.
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
The helper:
- chooses dirty
--uncommitted first
- otherwise uses current PR base if
gh pr view works
- otherwise uses
origin/main for non-main branches
- should be left in
--mode auto or forced to --mode branch for committed/PR work; do not force --mode local after committing
- writes only to stdout unless
--output or CODEX_REVIEW_OUTPUT is set
- supports
--dry-run and --parallel-tests
- supports
--full-access for nested review runs that need localhost bind/listen tests
- prints
codex-review clean: no accepted/actionable findings reported when the selected review command exits 0
Recursion guard:
- The helper exports
CODEX_REVIEW_HELPER_LEVEL=1 to the nested codex review process.
- If a review session tries to invoke the helper again, the helper exits
78 with nested codex-review invocation blocked.
- Use
CODEX_REVIEW_ALLOW_NESTED=1 only for intentional debugging dry runs; do not use it in normal closeout, GoalBuddy conveyor, or PR review flows.
Final Report
Include:
- review command used
- tests/proof run
- findings accepted/rejected, briefly why
- the clean review result from the final helper/review run, or why a remaining finding was consciously rejected
Do not run another Codex review solely to improve the final report wording. If the final helper run exited 0 and produced no accepted/actionable findings, report that exact run as clean.
