| name | codex-review |
| description | Runs OpenAI Codex as a local PR or uncommitted-diff reviewer and routes findings into the shared fix protocol. Triggers: '/codex-review', 'codex review', 'run codex review', 'babysit codex review', 'codex as a PR reviewer'. |
Codex Review
Runs one Codex review pass against a chosen target, classifies the outcome, and hands findings to the shared fix protocol. Does not reimplement opt-out parsing or the fix sequence.
When this skill applies
- The user wants Codex (the OpenAI Codex CLI) as a reviewer on the current PR branch, or on uncommitted work when no PR loop is active.
- The user asks to babysit or re-run Codex review after fixes.
Refusals
Respond with the quoted line exactly and stop:
- Opt-out gate exit 0:
/codex-review is disabled via CLAUDE_REVIEWS_DISABLED.
- Version or shape probe reports Codex unavailable:
/codex-review cannot run: Codex CLI is missing or the shape probe failed.
- Skill class is
down (wrapper outcome_class is codex_down): /codex-review cannot complete: Codex reviewer is down.
Gate exits other than 0 or 1 are blockers: stop without a probe or review invoke. Do not invent an opt-out refusal for a non-opt-out failure.
Sub-skills
| Skill | When | Produces |
|---|
reviewer-gates | Step 0 — opt-out semantics for external reviewers | Gate contract for reviews_disabled.py; refusal line shape |
pr-fix-protocol | Step 5 — classification is findings | Fix sequence, reply-and-resolve unit, unresolved-thread sweep |
If pr-fix-protocol is not installed when findings exist, stop with: /codex-review needs the pr-fix-protocol skill to apply findings.
Process checklist
- [ ] Step 0 — Opt-out gate
- [ ] Step 1 — Version and shape probe
- [ ] Step 2 — Target pick
- [ ] Step 3 — Run classifying review
- [ ] Step 4 — Classify outcome
- [ ] Step 5 — Route findings (or stop on clean / down)
Step 0: Opt-out gate
Before any other work, run:
python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer codex
- Exit 0 — Codex reviews are disabled: refuse with the opt-out line above. Do not probe, review, or fix.
- Exit 1 — continue.
- Any other exit — treat as a blocker and stop; do not skip the gate or continue as if it exited 1. Do not report the opt-out refusal line for a non-opt-out failure.
Gate semantics live in reviewer-gates (../reviewer-gates/SKILL.md). The shared script owns the token parse; this skill does not re-parse CLAUDE_REVIEWS_DISABLED.
Step 1: Version and shape probe
Probe the local Codex CLI so the run fails closed when the binary is missing or the installed shape does not match the contract.
- Contract owner: reference/cli-contract.md — probe command (
codex exec review --help), minimum shape signals, and fail-as-codex_down rule.
- Probe outcome: continue only when the probe reports a supported shape. On failure, refuse with the probe refusal line above (skill class
down).
Step 2: Target pick
Choose what Codex reviews:
| Context | Target |
|---|
| PR-loop caller (or an open PR on the current branch) | Diff against the PR base branch (--base) |
| Standalone run with no PR | Uncommitted work via --uncommitted (staged + unstaged + untracked) |
Do not invent a synthetic commit range when a base branch is available. Loop-caller wiring for base-branch resolution lives in reference/loop-integration.md.
Step 3: Run classifying review
Call scripts/run_codex_review.py (run_codex_review) against the chosen target on the classifying path.
- Classifying command:
codex exec [options] review --json … — this is the only path that emits the success JSONL stream Step 4 reads. Full surface: reference/cli-contract.md.
- Non-classifying form: plain
codex review (no exec, no --json) is not a classification input on the observed CLI; do not feed its stdout into Step 4.
- Contract owner: reference/cli-contract.md — wrapper entrypoint, required arguments (target, repo root, run-state directory), capture fields, and exit codes.
- Wrapper boundary (capture only): returns
completed or codex_down, plus exit_code, binary_version, jsonl_path, and agent_message. It does not emit skill classes down / clean / findings and does not parse findings.
- This skill's job: pass the Step 2 target, ensure
run_state_directory exists, and hand the capture outcome to Step 4. Do not parse raw Codex stdout inline outside the documented parser path. Fail closed on probe miss, non-usable stream, or codex_down.
Step 4: Classify outcome
Map the wrapper capture (and its JSONL observation) to exactly one skill-level class:
| Skill class | From wrapper | Meaning | Next action |
|---|
down | outcome_class == codex_down | Codex did not produce a usable review (tool failure, auth, crash, shape miss) | Refuse with the down line; stop |
clean | outcome_class == completed and findings parse empty | Review completed with no findings against the target | Report one-line clean summary; stop |
findings | outcome_class == completed and findings parse non-empty | Review completed with one or more addressable findings | Continue to Step 5 |
outcome_class is the capture success signal. A process exit_code of 0 does not mean success when the wrapper already set codex_down (for example a shape probe that exits 0 but lacks required flags).
Skill class ↔ CLI observation map
| Skill class | Maps from (cli-contract) | Signal |
|---|
down | codex_down rows; unrecognized probe shape | Non-usable review (exit 1/2 failures, config/auth/model errors, probe miss) |
clean | Wrapper completed and parse_codex_findings(agent_message) empty (blank text or structured []) | Usable review, zero addressable findings |
findings | Wrapper completed and parse_codex_findings(agent_message) non-empty (fenced JSON objects, freeform - [P#] bullets, or floor text) | Usable review with addressable findings |
Raw CLI failure vocabulary is codex_down only (reference/cli-contract.md). Skill steps and loop re-entry use down / clean / findings. Classification rules, findings parse, and payload fields live in reference/cli-contract.md.
Step 5: Route findings into the shared fix protocol
When the class is findings:
- Read
$HOME/.claude/skills/pr-fix-protocol/SKILL.md (or invoke pr-fix-protocol by name when the Skill tool is available).
- Pass the findings payload, PR scope when present, and worktree path.
- Apply the protocol end to end — failing test first when behavior is at stake, one fix commit, push when the caller requires it, reply and resolve per thread when the review is on a PR.
This skill does not restate the fix sequence. Orchestrator callers that re-enter after a push follow reference/loop-integration.md.
Ground rules
- One capability: run Codex review and classify; fixes go through
pr-fix-protocol.
- Compose, do not rebuild: opt-out via
reviews_disabled.py; fixes via pr-fix-protocol.
- Fail closed on opt-out, non-0/1 gate exit, probe failure, and
down.
- Preserve draft state of any open PR; this skill does not flip ready.
- Honor hooks on any commit the fix protocol creates.
Examples
User: `/codex-review`
Claude: [runs opt-out gate; on exit 1 probes Codex shape, picks base-branch or `--uncommitted` target, runs `codex exec … review --json`, classifies from JSONL, reports clean or routes findings; on non-0/1 gate exit stops as a blocker]
`CLAUDE_REVIEWS_DISABLED=codex`
Claude: `/codex-review is disabled via CLAUDE_REVIEWS_DISABLED.`
User: "babysit codex review on this PR"
Claude: [same flow; after findings, applies pr-fix-protocol, then re-runs the classifying review once for confirmation when the caller stays on this skill]
Gotchas
- Opt-out uses
CLAUDE_REVIEWS_DISABLED=codex. reviews_disabled.py --reviewer codex exit 0 disables the review; exit 1 continues the probe and wrapper. Standalone /codex-review stops with the opt-out refusal line and never runs the wrapper (no codex_down capture). Orchestrator gates map the same exit 0 to codex_down / codexDown bypass on the machine checklist. Export CLAUDE_REVIEWS_DISABLED=codex (alone or comma-joined with other reviewers). A gate parse failure for an unknown token is a blocker — stop rather than skipping the gate. The shared gate must list codex among known reviewers for Step 0 to accept the flag.
- Only
codex exec … review --json JSONL is classifiable. Plain codex review stdout is non-classifying. Only a Step 4 findings class enters Step 5.
- Wrapper capture is not skill classification. Step 5 consumes the skill-class payload from Step 4 (
down / clean / findings), built from the wrapper's capture fields and the findings parse.
- Uncommitted targets have no review threads. Fix protocol reply-and-resolve applies only when a PR carries threads; local-only runs stop after the fix commit path the protocol allows without a PR.
File index
| File | Purpose |
|---|
SKILL.md | Hub: opt-out, probe, target, classifying review, classify, fix handoff |
CLAUDE.md | Package map for agents opening this skill |
reference/cli-contract.md | CLI probe, wrapper capture, auth, cloud runbook, fixture-backed failure classes |
reference/loop-integration.md | Gate placement, threshold, opt-out, state fields, re-entry |
scripts/run_codex_review.py | Headless capture wrapper (run_codex_review) |
scripts/test_run_codex_review.py | Behavioral tests for the capture wrapper |
scripts/codex_down_classifier.py | Maps exit code and stream text to detail class and completed / codex_down |
scripts/parse_codex_findings.py | Parses agent text: fenced JSON, freeform bullets, then floor |
scripts/codex_review_scripts_constants/run_constants.py | Importable named constants for the capture wrapper |
scripts/codex_usage_probe.py | Weekly usage probe CLI (percent_left, window_reset, source) |
scripts/test_codex_usage_probe.py | Probe unit tests (app-server fixtures and gate helper) |
scripts/codex_review_scripts_constants/codex_usage_probe_constants.py | Named constants for the weekly usage probe |
Folder map
SKILL.md — orchestration steps and refusals.CLAUDE.md — purpose, trigger, key files.reference/ — stable homes for cli-contract and loop-integration detail.scripts/ — capture wrapper, classifier, findings parser, weekly usage probe, tests, fixtures, and constants package.scripts/run_codex_review.py — headless capture wrapper entrypoint.scripts/codex_down_classifier.py — detail-class and gate-outcome classifier.scripts/parse_codex_findings.py — findings parser entrypoint.scripts/codex_usage_probe.py — weekly usage probe entrypoint.scripts/codex_review_scripts_constants/ — importable constants package for skill scripts.
