# claude-codex-review

A pair of [Claude Code](https://docs.claude.com/claude-code) skills that hand a plan Claude just wrote over to OpenAI's `codex exec` CLI for a structured **premortem** — running two different codex models in parallel, looping until they agree the plan is shippable.

## Two skills, one repo

Pick the one that matches what you want codex to do:

| Skill | Sandbox | Codex sees | When to use |
| --- | --- | --- | --- |
| **`/codex-review`** | `--sandbox read-only` | Only what you pipe in via stdin | Fast, deterministic, safe to point at sensitive repos. Great for plan-only premortems where ground-truth verification isn't the point. |
| **`/codex-review-full`** | `--sandbox danger-full-access --full-auto` | The whole codebase plus the shell | Codex can read source files, run tests, follow imports, exercise scripts — bounded only by a prompt-level rule against destructive operations. Use when verification against the actual code matters more than speed. |

The two skills share the same premortem loop, the same dual-model setup (gpt-5.5 + gpt-5.4 at xhigh reasoning), the same convergence logic. They differ only in how much access codex gets and what categories of finding it reports back.

## The idea

When you're planning with Claude, you eventually want a second opinion. The usual move is "have codex look at it." That works, but a single codex run can miss things, and the failure mode is silent — codex says "looks good" and you ship something subtly broken.

These skills do four things differently:

1. **Premortem framing.** Codex isn't asked "is this plan good?" — it's told the plan has already failed and asked to enumerate the plausible causes. The brief is to find problems, not validate.
2. **Dual model.** Two codex runs in parallel — `gpt-5.5` and `gpt-5.4`, both at `xhigh` reasoning. Convergence between two independent voices is a stronger signal than one verdict, and the failure modes of the two models don't overlap much.
3. **Tight output schema.** Each codex run returns three things: **blockers** (must-fix-before-merge), **confidence** (0–10), and **questions** (structural ambiguities). No should-fixes, no nits, no style commentary — those are noise that paused the human on every round in earlier versions. The loop only pauses you for real blockers and real questions.
4. **Loop until convergence — but escape early when it's not converging.** Both runs emit an `OVERLAP` signal from round 2 onward so Claude can tell when rounds are restating instead of progressing and cut scope rather than keep refining. A `QUESTIONS` channel lets the models escalate genuine design ambiguities up to you via the same `AskUserQuestion` popup flow Claude already uses inside plan mode. Hard 5-round ceiling backstops the rest.

The question-passthrough is the part most people miss. Codex isn't just grading the plan; it's also allowed to ask. When it does, Claude doesn't guess — it surfaces the question to you, folds your answer back in as a decision, and resumes the loop. The two AIs co-plan and you stay the tiebreaker on structural calls.

## Install

```bash
# Read-only review skill (default)
curl -fsSL https://raw.githubusercontent.com/KamakuraCrypto/claude-codex-review/main/install.sh | bash

# Full-access review skill
curl -fsSL https://raw.githubusercontent.com/KamakuraCrypto/claude-codex-review/main/install.sh | bash -s -- full

# Both
curl -fsSL https://raw.githubusercontent.com/KamakuraCrypto/claude-codex-review/main/install.sh | bash -s -- both
```

Or clone and run the installer locally:

```bash
git clone https://github.com/KamakuraCrypto/claude-codex-review
cd claude-codex-review
bash install.sh both     # or: bash install.sh, bash install.sh full
```

Each skill's `SKILL.md` lands at `~/.claude/skills/<skill-name>/SKILL.md`. Claude Code auto-discovers them on the next session start.

## Prerequisites

- Claude Code installed and working.
- OpenAI's [Codex CLI](https://github.com/openai/codex) installed and authenticated (`codex --version` should print a version).
- Access to `gpt-5.5` and `gpt-5.4` via your OpenAI account (anything older with a comparable reasoning-effort dial works too; edit the relevant `SKILL.md` if you want different defaults).

## Safety model for `/codex-review-full`

`/codex-review-full` runs codex with `--sandbox danger-full-access --full-auto`. The sandbox itself doesn't filter destructive commands — the only guardrail is a prompt-level rule that codex is told to follow. Specifically, codex is told **not** to run:

- `rm`, `rmdir`, `unlink`, `shred`, or any other delete command.
- `git reset --hard`, `git checkout -- .`, `git clean -fd`, `git restore .`.
- Any `git push` variant (including `--force` / `--force-with-lease`).
- `git branch -D`, `git tag -d`, `git update-ref -d`, `git reflog expire`.
- `DROP TABLE`, `DROP DATABASE`, `DROP SCHEMA`, `TRUNCATE`, unguarded `DELETE FROM`.
- `kill` / `pkill` / `killall` against processes codex did not start itself.
- Redirections (`>`, `>>`) that overwrite tracked files.
- Anything intended to disable, bypass, or uninstall security tooling.
- `chmod` / `chown` that escalates privileges or changes ownership of project files.

If a check requires one of the above, codex reports the gap as a finding instead of running the command. Scratch writes under `/tmp/` are allowed; reads anywhere are allowed; network is allowed.

This is a trust model, not a sandbox enforcement. Don't point `/codex-review-full` at a repo you wouldn't trust a junior developer with full shell access to. Use `/codex-review` for anything sensitive.

## What's in this repo

- `SKILL.md` — the `/codex-review` skill.
- `codex-review-full/SKILL.md` — the `/codex-review-full` skill.
- `install.sh` — installer for either skill or both.
- `codex-review-full/install.sh` — standalone installer for just the full-access variant.
- `LICENSE` — MIT.

## Why these defaults

A few of the defaults are non-obvious. They're all there because of bugs that bit me in real sessions:

- **`/codex-review` bundles inputs via stdin, doesn't let codex read files.** Codex's bwrap sandbox sometimes denies its own internal filesystem reads, especially on `gpt-5.5`. Symptom: clean exit, blank output. Switching `--sandbox` modes doesn't help — the loopback is in how the container is set up. Pre-inlining everything bypasses the whole problem. `/codex-review-full` accepts the loopback risk deliberately, in exchange for review depth; if you hit it there, bounce to `/codex-review` for that round.
- **Stderr is not suppressed on review runs.** The `2>/dev/null` reflex hides the exact diagnostic you need when a run fails silently. Suppress it on chatty edit runs if you want; never on reviews.
- **The skills don't re-ask the user for model and effort settings each invocation.** The defaults are tuned for these specific workflows; you get to override them via the per-model launch lines if you need something else.
- **Three-output schema, not a five-category review.** Earlier versions had codex return `BLOCKER` / `SHOULD-FIX` / `NIT` + a verdict line + a recommendation. That generated long reports and forced Claude to pause you on nearly every round to confirm fixes. The current schema returns only what's actually blocking, plus a confidence score, plus questions. Most rounds resolve without any human input.

## Credit

Built for the way I personally use Claude Code for planning — dual-codex review as a hard quality gate before any code is written. Inspired by the broader community pattern of cross-AI verification, then specialized into a workflow that actually converges in 1–3 rounds for most plans.

## License

MIT — see [LICENSE](LICENSE).