# Cmd Codex Review Unstaged

> Get a second opinion on what Claude just implemented from Codex (codex exec headless mode). Pipes Claude's summary plus the working-tree diff to codex, asks codex to leverage cmd-pr-follow-up and cmd-pr-edgecase methodology to surface bugs, test gaps, edge cases, and simplification opportunities, then synthesizes a prioritized iteration plan from the feedback. Triggers on "/cmd-codex-review-unsta…

- **Type:** Skill
- **Install:** `agentstack add skill-olshansk-agent-skills-cmd-codex-review-unstaged`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Olshansk](https://agentstack.voostack.com/s/olshansk)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Olshansk](https://github.com/Olshansk)
- **Source:** https://github.com/Olshansk/agent-skills/tree/main/skills/cmd-codex-review-unstaged

## Install

```sh
agentstack add skill-olshansk-agent-skills-cmd-codex-review-unstaged
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Codex Review Unstaged 

Use `codex exec` as an independent reviewer on the working-tree changes Claude just made. Codex sees only the summary + diff (no conversation history), so its critique catches things Claude rationalized into "good enough" during implementation. The output is a prioritized iteration plan — what to fix now, what to defer, what to reject.

- [When to use](#when-to-use)
- [Instructions](#instructions)
- [Codex prompt](#codex-prompt)
- [Output format](#output-format)
- [Notes](#notes)

## When to use

- After Claude finishes a non-trivial implementation pass and before commit
- When the user says "review my changes with codex", "have codex check what I just did", or `/cmd-codex-review-unstaged`
- As an outside cross-check before opening a PR — complements `cmd-pr-follow-up` (Claude self-review) and `cmd-pr-edgecase` (edge-case sweep) by adding a fresh pair of eyes that didn't write the code

## Instructions

### 1. Build Claude's implementation summary

Write a short summary of what was just implemented. Keep it **factual, not promotional**:

- What was the goal?
- What files changed and why?
- What design decisions were made (and what was rejected)?
- What was deliberately deferred (TODOs, follow-ups, scope cuts)?
- What was tested manually vs. covered by automated tests?

This summary anchors codex's review — without it, codex will judge the diff against a generic standard instead of the actual intent.

### 2. Capture the diff

Default scope: **`git diff HEAD`** — captures both staged and unstaged working-tree changes since the last commit.

```bash
DIFF_FILE=$(mktemp -t codex-diff.XXXXXX.patch)
SUMMARY_FILE=$(mktemp -t codex-summary.XXXXXX.md)
OUT_FILE=$(mktemp -t codex-review.XXXXXX.md)

git diff HEAD > "$DIFF_FILE"
git status --short >> "$DIFF_FILE"
```

If the user explicitly asks for unstaged-only or branch diff, swap in:
- Unstaged only: `git diff`
- Branch vs main: `git diff main...HEAD`
- Include untracked: append `git ls-files --others --exclude-standard` separately

Write the summary from step 1 verbatim to `$SUMMARY_FILE` using the Write tool.

**Sanity check before invoking codex:**
- If `$DIFF_FILE` is empty (no changes), tell the user there's nothing to review and stop.
- If the diff is enormous (>50k lines), warn the user — codex will still run but the review quality drops on huge surfaces. Suggest narrowing scope (e.g., per-file or per-phase review).

### 3. Run codex in headless review mode

```bash
codex exec \
  --sandbox read-only \
  --skip-git-repo-check \
  --color never \
  --output-last-message "$OUT_FILE" \
  "$(cat  **Note:** the prompt references `$SUMMARY_FILE` and `$DIFF_FILE` by absolute path. Since codex runs read-only in the same working directory, it will read those tempfiles when instructed. Use full paths in the heredoc (substituted by the shell) so codex can locate them without ambiguity.

### 4. Present codex's raw feedback

Show the contents of `$OUT_FILE` to the user verbatim under a heading:

```markdown
## Codex review

> Independent review from `codex exec` — diff + summary only, no conversation context.

```

Do NOT paraphrase. The user wants codex's voice.

### 5. Synthesize an iteration plan

Read codex's findings and convert them into a concrete iteration plan. For each finding, decide:
- **Apply now** — fix in this iteration before commit
- **Defer with TODO** — legitimate but out of scope; add a `TODO_TECHDEBT` / `TODO_IDEA` comment in the relevant file
- **Reject** — wrong, irrelevant, or codex misunderstood context Claude has

Don't blindly accept everything. If a finding is wrong (codex missed context, misread the diff, or proposed something contrary to the project's conventions), mark it rejected and explain why.

### 6. Cleanup

```bash
rm -f "$DIFF_FILE" "$SUMMARY_FILE" "$OUT_FILE"
```

## Codex prompt

The exact prompt is embedded in [step 3](#3-run-codex-in-headless-review-mode). Key requirements when adapting it:
- Tell codex it's reviewing another agent's diff (sets tone)
- Point codex at the skill methodology files in `~/.codex/skills/` — those are symlinked to the repo and codex can read them in read-only mode
- Demand `file:line` references — vague critique is useless
- Force a verdict line for triage at a glance
- Allow codex to say "looks good" — no manufactured issues

## Output format

After codex returns, present the result as three sections in order:

### 1. Codex's raw review

Quoted verbatim under a `## Codex review` heading.

### 2. Iteration plan

Prioritized checklist Claude will execute (or propose to execute) next. Group by decision:

```markdown
**Apply now (P0):**
- [ ] `path/to/file.py:42` — fix off-by-one in pagination loop
- [ ] `path/to/test_file.py` — add test for empty-list case

**Apply now (P1):**
- [ ] `path/to/other.py:88` — extract duplicated normalization helper

**Defer with TODO:**
- [ ] `path/to/file.py:120` — add `TODO_TECHDEBT` for connection pooling
      Why deferred: not blocking; needs separate evaluation of pgbouncer vs in-app pooling

**Rejected:**
- [ ] Codex suggestion: "Wrap entire handler in try/except"
      Why rejected: framework already converts exceptions to 500s; adding try/except would swallow stack traces
```

### 3. Changelog

Table summarizing every codex finding and what Claude decided:

| S | Finding | Severity | Decision | Reason |
|---|---------|----------|----------|--------|
| 🟢 | Off-by-one in pagination at `loader.py:42` | High | Apply now | Genuine bug, codex caught it |
| 🟡 | Connection pooling | Medium | Defer | TODO_TECHDEBT added; out of scope |
| 🔴 | Wrap handler in try/except | Low | Reject | Framework handles it; would hide errors |
| 🟢 | Add empty-list test in `test_loader.py` | Medium | Apply now | Real gap, test is small |

> 🟢 Apply now · 🟡 Defer (with TODO) · 🔴 Reject · ⚪ Already addressed

End with a one-line tl;dr: e.g., "_3 fixes to apply, 1 TODO to add, 1 suggestion rejected. Verdict: minor-tweaks._"

### 6. Ask before applying

After presenting the iteration plan, **ask the user** whether to apply the P0/P1 fixes now or wait. Don't auto-apply — the user wants to see the plan first.

## Notes

- **Codex needs auth** — if `codex exec` errors with auth issues, tell the user to run `codex login` and stop.
- **Read-only sandbox** — codex cannot modify files even if it tries. This is intentional.
- **Skill paths are symlinked** — `~/.codex/skills/cmd-pr-follow-up/SKILL.md` resolves to this repo via `make link-skills`. If codex reports it can't read those paths, the user may need to run `make link-skills` from `~/workspace/agent-skills`.
- **Don't loop** — one codex review per invocation. After applying fixes, the user can re-run for another pass if desired.
- **Untracked files** — `git diff HEAD` does NOT show untracked files. If the implementation added new files that aren't yet tracked, mention this to the user and offer to `git add -N` them so they appear in the diff (intent-to-add stages the path without content, making the diff include them).
- **Companion skill** — pair with `cmd-codex-review-plan` (pre-implementation plan review) for full coverage: codex reviews the plan before execution AND the diff after.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Olshansk](https://github.com/Olshansk)
- **Source:** [Olshansk/agent-skills](https://github.com/Olshansk/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-olshansk-agent-skills-cmd-codex-review-unstaged
- Seller: https://agentstack.voostack.com/s/olshansk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.