AI how-to notes · 2026-09-17 · last run 2026-09-17 · 한국어 원문

Reviewing code with Codex CLI before you commit — codex review --uncommitted on Windows

One line summary

codex review --uncommitted bundles up everything you haven't committed yet — staged or not — plus untracked new files, and reviews the lot. Run against a temp repository with two deliberately planted bugs, all three of its findings matched real test failures. That said, codex could not run the tests itself, and --uncommitted cannot be combined with a review instruction.

Who this is for

• Anyone who wants a review pass from a script or an agent before committing
• Anyone who wants to know what codex review looks at, and what shape the result comes back in
• Anyone who wants the review saved to a file

Test environment

All three review attempts had < /dev/null attached so stdin ended immediately. Related note: codex exec hangs waiting on stdin.

The options in the help text

From codex review --help, the options that choose what gets reviewed:

Usage: codex review [OPTIONS] [PROMPT]

      --uncommitted
          Review staged, unstaged, and untracked changes

      --base <BRANCH>
          Review changes against the given base branch

      --commit <SHA>
          Review the changes introduced by a commit

      --title <TITLE>
          Optional commit title to display in the review summary

The command table in the official docs says the same thing. --uncommitted: "Review staged, unstaged, and untracked changes." (learn.chatgpt.com/docs/developer-commands?surface=cli, checked 2026-09-17)

codex review --help has no -o and no --json. Both live on codex exec review --help, so that's what we used to get the result into a file (section 3).

1. Setting up a repo with bugs in it

We committed a correct stats.py, then introduced two bugs as uncommitted changes. In clamp, the upper bound hi was wrongly changed to lo, and the newly added median doesn't handle even-length input. The test file test_stats.py was left as an untracked new file.

37d0534 add stats
 M stats.py
?? test_stats.py
--- git diff ---
 def clamp(x, lo, hi):
-    return max(lo, min(x, hi))
+    return max(lo, min(x, lo))
+
+
+def median(nums):
+    s = sorted(nums)
+    mid = len(s) // 2
+    return s[mid]

We ran the tests before the review. The tests also encode a requirement that an empty list raises ValueError.

PASS average([1, 2, 3]) == 2
PASS average([]) == 0.0
FAIL clamp(5, 0, 10) == 5
PASS clamp(-1, 0, 10) == 0
FAIL clamp(99, 0, 10) == 10
PASS median([3, 1, 2]) == 2
FAIL median([4, 1, 3, 2]) == 2.5
FAIL median([]) raises ValueError -> IndexError
4 failed

2. Running codex review --uncommitted

cd review
codex review --uncommitted < /dev/null; echo "codex exit=$?"

The whole command, including the git status checks either side of it, took 57.8 seconds and exited 0. The review body went to standard output; the run banner and the commands codex executed went to standard error. The banner printed these values, none of which we specified.

model: gpt-6-astra
approval: never
sandbox: read-only
user
current changes

The review on standard output is a one-paragraph summary plus three prioritized findings (the line explanations are trimmed).

The patch breaks clamp and fails the stated median expectations for even-length and empty inputs. Test execution was unavailable because Python was not installed on PATH; these failures are evident from inspection.

Full review comments:

- [P1] Restore the upper bound in clamp — C:/Users/User/AppData/Local/Temp/longtail_A2/review/stats.py:8-8
- [P2] Average the middle values for even-length inputs — C:/Users/User/AppData/Local/Temp/longtail_A2/review/stats.py:13-14
- [P2] Raise ValueError for an empty median input — C:/Users/User/AppData/Local/Temp/longtail_A2/review/stats.py:12-14

After the review, git status was identical to before ( M stats.py, ?? test_stats.py). No files were modified.

Checking the findings against real results

We verified the numbers inside the findings separately in Python.

clamp(5, 0, 10) = 0
clamp(99, 0, 10) = 0
clamp(-1, 0, 10) = 0
median([4, 1, 3, 2]) = 3
median([]) -> IndexError list index out of range

All four test failures were covered by the three findings, and there were no findings unrelated to a failure. The claim in the P1 explanation — that for ordinary numeric input clamp always returns lo — held up too: all three inputs returned 0.

Applying the findings to a copy (restoring hi in clamp; raising ValueError for empty input and averaging the two middle values for even-length input in median) and re-running the tests gave 0 failed and exit code 0.

codex could not run the tests

The review summary says "Python was not installed on PATH". Standard error shows codex ran python -B test_stats.py through PowerShell and got a CommandNotFoundException. The explanatory part of the error was garbled Korean text we could not read.

    + CategoryInfo          : ObjectNotFound: (python:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException

When we looked for it ourselves on the same PC with pwsh -NoProfile, we got C:\Users\User\AppData\Local\Programs\Python\Python312\python.exe. Only the environment codex runs commands in failed to find python. A comparison of the PowerShell environment across sandbox modes is written up separately in Codex sandbox read-only vs workspace-write. So this review was a judgment made by reading the code, and the summary said as much: "evident from inspection".

3. Getting the result into a file — codex exec review

codex exec review --uncommitted --ephemeral -o ../review_out.md < /dev/null; echo "codex exit=$?"

55.7 seconds, exit code 0. review_out.md was 1327 bytes, and the three problems found and their priorities (one P1, two P2) matched section 2. The two P2 titles were worded differently (Average the two middle values for even-length inputs, Reject empty median inputs with ValueError). The explanatory sentences differed slightly too, and the file paths were printed with backslashes, as C:\Users\...\stats.py:8-8. The same review also appeared once more on standard output. codex's python -B test_stats.py again failed with the same CommandNotFoundException.

Results

What failed

Round 2 attached a review instruction to --uncommitted and was rejected outright.

error: the argument '--uncommitted' cannot be used with '[PROMPT]'

Usage: codex review --uncommitted [PROMPT]

The Usage line in the help text shows [PROMPT], but in 0.153.4 you cannot pass --uncommitted and an instruction at the same time. Narrowing the scope with something like "only look at clamp" is not possible in that combination.

codex failing to run the tests is also a limit of this experiment. We did not establish why python wasn't found in that environment.

What we did not test

• We read --base, --commit and --title in the help text but did not run them.
• We did not measure timing or finding quality on a repository with many files or large changes.
• We did not separate out how staged-only changes and deleted files are picked up in a review.
• For the config key review_model we only saw the documented description, "Optional model override used by /review (defaults to the current session model)." — we did not use it (learn.chatgpt.com/docs/config-file/config-reference, checked 2026-09-17).
• We did not check where the banner's sandbox: read-only and approval: never values are decided. We did not open the user config file.
• We did not look at the shape of codex exec review --json output.
• We did not test whether a change with no bugs at all produces false positives.
• We did not check languages other than Python, macOS or Linux, or Command Prompt (cmd.exe).

Related notes

• Codex sandbox read-only vs workspace-write
• Writing codex exec results to a file
• codex exec hangs waiting on stdin
• Switching the Codex model with -m