codex-review
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'.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 7
- Forks
- 1
01 前言 Front Matter
- 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'.
02 资源文件 24
- 参考文档reference/cli-contract.md13.6 KB
- 参考文档reference/loop-integration.md6.9 KB
- 脚本scripts/codex_down_classifier.py3.2 KB
- 脚本scripts/codex_review_scripts_constants/__init__.py58 B
- 脚本scripts/codex_review_scripts_constants/classifier_constants.py848 B
- 脚本scripts/codex_review_scripts_constants/codex_usage_probe_constants.py2.4 KB
- 脚本scripts/codex_review_scripts_constants/findings_constants.py530 B
- 脚本scripts/codex_review_scripts_constants/run_constants.py1.7 KB
- 脚本scripts/codex_usage_probe.py18.9 KB
- 脚本scripts/fixtures/auth_failure_synthetic.txt71 B
- 脚本scripts/fixtures/config_load_failure_v0.125.0.txt98 B
- 脚本scripts/fixtures/freeform_findings_v0.144.3.txt420 B
- 脚本scripts/fixtures/model_rejection_v0.125.0.jsonl573 B
- 脚本scripts/fixtures/structured_findings.txt250 B
- 脚本scripts/fixtures/success_stream_v0.144.3.jsonl585 B
- 脚本scripts/fixtures/unknown_failure_synthetic.txt57 B
- 脚本scripts/fixtures/usage_limit_synthetic.txt95 B
- 脚本scripts/parse_codex_findings.py6.6 KB
- 脚本scripts/run_codex_review.py20.9 KB
- 脚本scripts/test_codex_down_classifier.py4.5 KB
- 脚本scripts/test_codex_usage_probe.py22.7 KB
- 脚本scripts/test_parse_codex_findings.py3.9 KB
- 脚本scripts/test_run_codex_review.py31.4 KB
- 脚本test_skill_scaffold.py7.1 KB
03 SKILL.md 正文
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(wrapperoutcome_classiscodex_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_downrule. - 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(noexec, 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
completedorcodex_down, plusexit_code,binary_version,jsonl_path, andagent_message. It does not emit skill classesdown/clean/findingsand does not parse findings. - This skill's job: pass the Step 2 target, ensure
run_state_directoryexists, 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, orcodex_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 invokepr-fix-protocolby name when theSkilltool 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 viapr-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
<example>
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]
</example>
<example>
CLAUDE_REVIEWS_DISABLED=codex
Claude: /codex-review is disabled via CLAUDE_REVIEWS_DISABLED.
</example>
<example> 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] </example>
Gotchas
- Opt-out uses
CLAUDE_REVIEWS_DISABLED=codex.reviews_disabled.py --reviewer codexexit 0 disables the review; exit 1 continues the probe and wrapper. Standalone/codex-reviewstops with the opt-out refusal line and never runs the wrapper (nocodex_downcapture). Orchestrator gates map the same exit 0 tocodex_down/codexDownbypass on the machine checklist. ExportCLAUDE_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 listcodexamong known reviewers for Step 0 to accept the flag. - Only
codex exec … review --jsonJSONL is classifiable. Plaincodex reviewstdout is non-classifying. Only a Step 4findingsclass 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.
04 同仓库更多 Skills
update
Fast-forwards a local repository's main branch to a remote's main after confirming the repo path and source remote through AskUserQuestion. Use when the user says '/update', 'update main', 'fast-forward main', 'sync main from origin', 'pull latest main into <path>', or 'bring main up to date'.
source-command-sr-loop
Converging cleanup loop: repeat /simplify until clean, then repeat /code-review --fix until clean
skill-builder
Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers, enforce deterministic scripts. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, skill composition, description trigger catalog, deterministic skill scripts.
session-tidy
Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.
session-log
Logs a session report as an HTML page, tracks vault context, extracts decisions, and outputs a /rename command. Use for /session-log, 'journal this session', 'log this work', 'session report', 'summarize/log/record this session', 'save session', 'capture session', or 'document what we did'.
run-claude-dev-env
Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.