codex-review

Code review by Codex

An independent reviewer that hasn't seen this conversation is genuinely useful: it won't inherit your assumptions about the change. Use it as a second pass, not a replacement for your own read.

Pick the scope

git -C <repo> diff                      # uncommitted, unstaged
git -C <repo> diff --staged             # staged
git -C <repo> diff main...HEAD          # whole branch vs main
git -C <repo> diff --stat main...HEAD   # size check first

Check the size before sending. Under ~1500 changed lines, pipe the diff in directly. Larger than that, point Codex at the files instead and let it read selectively — a giant pasted diff degrades the review.

Run it

Small or medium change — pipe the diff as the prompt body:

{ echo "Review this diff as a senior engineer on this codebase. Report findings grouped by severity (Critical / Major / Minor / Nit). For each: file:line, what's wrong, and the concrete fix. Focus on correctness, security, error handling, race conditions, and missed edge cases. Skip style unless it hides a bug. If you find nothing at a severity level, say so rather than inventing findings."; echo; git -C <repo> diff main...HEAD; } | codex-run -C <repo> --timeout 1200 -

Large change or a whole module — let Codex read the tree itself:

codex-run -C <repo> --timeout 1800 \
  "Review the changes on this branch versus main (run git diff main...HEAD yourself, and read the surrounding files for context). Report findings grouped by severity (Critical/Major/Minor/Nit) with file:line and a concrete fix for each. Prioritise correctness, security, error handling, and missed edge cases."

Both run read-only — Codex cannot modify the working tree.

Handling the results

1. Verify each finding before repeating it. Open the cited file:line. Codex reviews without conversation context and will sometimes flag intentional behaviour, or cite a line that doesn't say what it claims. A review that forwards false positives is worse than no review.
2. Present it as three groups: confirmed findings (with your verification), findings you checked and disagree with (say why), and anything you couldn't verify.
3. Don't auto-fix. Show the user the findings and let them choose. If they ask for fixes, apply them yourself — you have the conversation context.
4. Attribute clearly: these are Codex's findings, and your assessment of them.