Cmd Codex Review Unstaged

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.

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

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

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:

**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
• Source: Olshansk/agent-skills
• License: MIT

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