codex

codex-review-cc

A Claude Code plugin that summons OpenAI Codex as an adversarial reviewer and debates it to convergence. Codex is the hard gate — the agent (Claude) edits the code or doc; Codex decides when the work passes. Neither command ever commits.

Command	Reviews	Gate before
/codex:spec-review	a superpowers spec or plan doc	writing/executing the plan
/codex:code-review	the current branch's implementation diff	finishing the branch

Requirements

• The codex CLI on PATH, version ≥ 0.140.0 (both commands preflight-check this).
• Run from inside a git repo.
• Optional: node on PATH enables structured JSON mode for /codex:code-review (codex --output-schema). Without it the command falls back to markdown parsing — same gate, slightly more fragile.
• Codex runs codex exec --sandbox read-only --ephemeral — it reads the repo but never writes. All edits come from Claude.

Install

As a plugin (recommended)

/plugin marketplace add vukhanhtruong/codex-review-cc
/plugin install codex@codex-review-cc

The plugin resolves its library and checklists from ${CLAUDE_PLUGIN_ROOT} automatically — nothing to copy.

Via npx

npx codex-review-cc            # install (adds the marketplace + installs the plugin)
npx codex-review-cc update     # update to the latest version (auto-prunes stale caches)
npx codex-review-cc prune      # remove stale cached versions (keeps the active one)
npx codex-review-cc help       # usage
# flag: --scope <user|project>   (default: user)

Thin wrapper over Claude Code's own plugin system — it runs claude plugin marketplace add

• claude plugin install codex@codex-review-cc for you (and marketplace update + plugin update on update). Claude Code stays the single source of truth, so there are no parallel copies to drift or go stale. Restart Claude Code after install/update.

Manual (no marketplace)

git clone https://github.com/vukhanhtruong/codex-review-cc.git
cd codex-review-cc && ./install.sh

Copies the commands, codex-lib.sh + helpers/, and both checklists into ${CLAUDE_HOME:-$HOME/.claude}/commands/codex. The commands resolve the plugin root first, then a project-local .claude/commands/codex checkout, then this global install — so any closer copy overrides the global one.

How it fits a spec → plan → code lifecycle

These commands plug in as quality gates between phases. Each runs after you finish a phase and before you proceed — Codex must approve, or you stay in the current phase.

writing-plans ──► spec/plan written
     │
     ▼
┌─────────────────────────────┐
│ /codex:spec-review          │  ← gate: Codex debates the spec/plan
│   APPROVED → stamps marker  │
└─────────────────────────────┘
     │  "proceed to writing-plans" (spec) / "proceed to executing-plans" (plan)
     ▼
executing-plans ──► code written, tests pass
     │
     ▼
┌─────────────────────────────┐
│ /codex:code-review          │  ← gate: Codex debates the diff
│   APPROVED → verify ran     │
└─────────────────────────────┘
     │  "proceed to finish the branch"
     ▼
you commit + merge/PR

On approval each command tells you the next step. The commands never commit — you do.

Usage

/codex:spec-review [spec|plan] [name-keyword]

/codex:spec-review                      # latest spec under docs/superpowers/specs
/codex:spec-review plan                 # latest matching plan
/codex:spec-review spec evals-dataset   # spec whose name matches "evals-dataset"

Searches docs/superpowers/specs/*-design.md and docs/superpowers/plans/. Debate runs in a fork subagent (falls back to inline if forks are unavailable) so the back-and-forth stays out of your main conversation. Loop cap: 5 rounds. On approval it stamps codex-approved <date> into the doc's frontmatter — a durable marker.

/codex:code-review [base]

/codex:code-review        # diff current branch vs main
/codex:code-review dev    # diff vs an alternate base ref

Reviews the committed diff + working-tree diff + untracked file contents (rebuilt each round so your edits stay in view) across five lenses — correctness, security, reliability, simplification, performance — driven by the security, reliability, and simplification checklists shipped in reference/. The Codex prompt is built as XML contract blocks (grounding, finding-bar, calibration) so findings stay grounded and noise-free. Secrets are redacted from the payload by filename and by content. When a spec/plan doc is found for the branch, Codex reads it read-only and flags any diff-vs-design divergence. Runs your test command at approval so it never green-lights a broken build. Loop cap: 5 rounds.