codex-review

What this skill does

# Cross-Model Code Review with Codex CLI

Cross-model validation using the `codex` binary directly. Claude writes code, Codex reviews it. Different architecture, different training distribution, no self-approval bias.

**Core insight:** Single-model self-review is systematically biased. Cross-model review catches different bug classes because the reviewer has fundamentally different blind spots than the author.

**How to read this skill:** the patterns and decision trees below are guidelines. Pick what fits, blend when needed. The rules marked ⚠️ are different: they're real `codex` CLI behaviors, not procedural ceremony. Skipping the scope flag genuinely hangs the call; piping to `tail` genuinely loses output. Treat ⚠️ rules as facts about the tool, not opinions about workflow.

**Prerequisite:** The `codex` CLI must be installed and authenticated. Verify with `codex --version`. User defaults live in `~/.codex/config.toml`; respect them.

**Direction:** Claude → Codex only. For the bidirectional skill (also handles Codex → Claude with the `claude -p` gotchas around `yield_time_ms` and variadic flags), use `/hyperskills:cross-model-review` instead.

---

## ⚠️ Non-Negotiable Rule: Always pass a scope flag to `codex review`

A bare `codex review` (no scope) is the #1 cause of failures: it hangs or produces 100KB+ blob output. **Always specify exactly one scope flag:**

| Want to review          | Command                       |
| ----------------------- | ----------------------------- |
| Branch since main       | `codex review --base main`    |
| Single commit           | `codex review --commit <SHA>` |
| Working tree (unstaged) | `codex review --uncommitted`  |

For anything outside this trio (spec docs, single files, custom personas, focused passes), use `codex exec "PROMPT"` with explicit scope in the prompt, never bare `codex review`.

If output exceeds ~100KB, the diff is too large for one pass. Split per commit, or use `codex exec` with a narrower prompt ("Review error handling only").

---

## ⚠️ Capture Output to a File: Don't Pipe to `tail`

Never pipe a review to `| tail -N`. Three failure modes:

1. **The pipe buffers until EOF.** `tail` reads the whole stream before producing output, so the agent gets nothing until codex exits or times out, no progress signal mid-review.
2. **Reviews put the verdict near the top, not the bottom.** Findings sort by severity (BLOCKER first), so `tail -300` cuts exactly the part you want.
3. **A file lets a human watch progress live.** `tail -f /tmp/review.txt` in another terminal streams the review in real time, completely independent of the agent's call.

**Right pattern:** pick a non-colliding filename, redirect, then read it back.

```bash
# mktemp so parallel/repeat reviews don't clobber each other.
# Bake the scope into the slug so it's self-describing under tail -f.
out=$(mktemp -t codex-review-pre-pr.XXXXXX) && echo "$out"

codex review --base main > "$out" 2>&1
codex exec --sandbox read-only "PROMPT" > "$out" 2>&1
```

If `mktemp` isn't handy: `out=/tmp/codex-review-$$-$(date +%s).txt`. Echo the path before the redirect so a human running `tail -f` knows where to look. After exit, `Read` (or `cat`) the file. It persists across turns, re-read instead of re-running.

---

## Two Ways to Invoke Codex

| Mode           | Command                                                     | Best For                                                    |
| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| `codex review` | Structured diff review with prioritized findings            | Pre-PR reviews, commit reviews, WIP checks                  |
| `codex exec`   | Freeform non-interactive deep-dive with full prompt control | Security audits, architecture, focused investigation, specs |

### Scope flags (`codex review` only)

| Flag              | Purpose                     |
| ----------------- | --------------------------- |
| `--base <BRANCH>` | Diff against base branch    |
| `--commit <SHA>`  | Review a specific commit    |
| `--uncommitted`   | Review working tree changes |

### Sandbox & ergonomics flags (both modes)

| Flag                                         | When                                                           |
| -------------------------------------------- | -------------------------------------------------------------- |
| `--sandbox read-only`                        | Default for review work, no writes                             |
| `--sandbox workspace-write`                  | Review + apply suggested fixes                                 |
| `--full-auto`                                | Alias for `--ask-for-approval never --sandbox workspace-write` |
| `--dangerously-bypass-approvals-and-sandbox` | Last resort; explicit user request only                        |
| `-C <DIR>` / `--cd <DIR>`                    | Run in another worktree without `cd`                           |
| `--skip-git-repo-check`                      | Running from a non-repo directory                              |
| `--add-dir <DIR>`                            | Extend read access to another path                             |
| `--ephemeral`                                | One-shot session, no persistence                               |
| `--json` / `--output-last-message <FILE>`    | Capture structured output to a file                            |
| `-c model_reasoning_effort="xhigh"`          | Spec/RFC review only (see Effort Policy)                       |

### Effort override policy

| Reviewing                       | Effort flag                               |
| ------------------------------- | ----------------------------------------- |
| Code (commit / diff / PR / WIP) | **None**, defer to `~/.codex/config.toml` |
| Spec / RFC / design doc         | `-c model_reasoning_effort="xhigh"`       |

Specs are higher-stakes than diffs, a subtle architectural mistake compounds across the eventual implementation. Code diffs are smaller scope and the user's configured effort is fine.

**Never** specify `--model`, `-m`, or `-c model=` to override the model itself. User config is authoritative.

---

## Review Patterns

### Pattern 1: Pre-PR Full Review (default)

The standard review before opening a PR. Use for any non-trivial change.

```
Step 1, structured review (catches correctness + general issues):
  codex review --base main

Step 2, security deep-dive (if code touches auth, input handling, or APIs):
  codex exec "<security prompt from references/prompts.md>"

Step 3, fix findings, then re-review:
  codex review --base main
```

### Pattern 2: Commit-Level Review

Quick check after each meaningful commit.

```bash
codex review --commit <SHA>
```

### Pattern 3: WIP Check

Review uncommitted work mid-development. Catches issues before they're baked in.

```bash
codex review --uncommitted
```

### Pattern 4: Focused Investigation

Surgical deep-dive on a specific concern (error handling, concurrency, data flow).

```bash
codex exec --sandbox read-only \
  "You are a senior <DOMAIN> engineer. Analyze <CONCERN> in the changes
   between main and HEAD. For each issue: cite file and line, explain the
   risk, suggest a concrete fix. Confidence threshold: 0.7."
```

### Pattern 5: Spec / RFC Review

Reviewing prose (markdown design docs) before code is written.

```bash
codex exec -c model_reasoning_effort="xhigh" --sandbox read-only \
  "You are a senior staff engineer doing a candid pre-implementation review of
   <PATH>. The author wants sharp, unsentimental analysis. For each finding:
   severity (BLOCKER / HIGH / MEDIUM / LOW), confidence (>= 0.7 only), location
   (file path + section heading), the issue, a concrete fix.
   End with a one-paragraph go/no-go verdict."
```

### Pattern 6: Single-File / Focused-Path Review

Review one file or directory rather than a full diff.

```bash
codex exec --sandbox read-only