codex-review Skill: Agent Scripts

Codex code review closeout skill from steipete/agent-scripts. Runs Codex’s built-in code review as a final closeout check before commit/ship.

Overview

codex-review is a skill for running Codex’s codex review command as a closeout verification step. It is distinct from Guardian’s auto_review approval routing — this is a developer-driven final check, not an automated gatekeeper.

The skill targets three scenarios:

1. Dirty local changes — uncommitted work pending review
2. Branch/PR work — comparing against base branch (main or PR target)
3. Committed single changes — specific commit SHA review

Core Contract

Rule	Description
Advisory only	Treat review output as advisory; never blindly apply
Verify findings	Read the real code path and adjacent files for every finding
Read dependency docs	When finding depends on external behavior, read docs/source/types
Reject wisely	Reject unrealistic edge cases, speculative risks, broad rewrites
Prefer small fixes	Small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class
Iterative	Keep going until review returns no accepted/actionable findings
Rerun after fixes	If review-triggered fix changes code, rerun focused tests and rerun review
Inline comments only	Add inline comment only when it explains a real invariant or ownership decision future reviewers should know
No push on review	Do not push just to review; push only when user requested push/ship/PR update

Target Selection

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. Run the plain base review first, then do a local/manual follow-up pass if custom instructions are needed.

Open PR (use actual base)

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

Committed single change

codex review --commit HEAD

Parallel Closeout Pattern

Format first if formatting can change line locations, then 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 either leads to edits, rerun affected tests and rerun review until clean.

Context Efficiency

Codex review is usually noisy. Default to a subagent filter when available:

Ask the subagent 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 Script

Bundled helper path:

~/.codex/skills/codex-review/scripts/codex-review --help
# or from agent-scripts install:
/Users/steipete/Projects/agent-scripts/skills/codex-review/scripts/codex-review --help

Helper behavior:

• Chooses dirty --uncommitted first
• Falls back to 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 in the review summary:

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

Related Notes

• Codex CLI documentation
• Claude Code review patterns
• AI coding workflow best practices

Source

• https://github.com/steipete/agent-scripts/blob/main/skills/codex-review/SKILL.md