How to review uncommitted changes with Codex

Reviewing uncommitted changes is useful before a commit, before opening a pull request, or after a burst of edits that touched several files. It lets you inspect the current working tree as a single change set instead of waiting until the changes are already recorded in Git history.

The Codex CLI includes codex review --uncommitted for this exact job. In the current CLI, the --uncommitted flag tells Codex to review staged changes, unstaged changes, and untracked files from the repository you run the command in.

Keep the working tree focused when possible, because smaller change sets usually produce clearer findings. Review output is heuristic rather than authoritative, and the diff plus surrounding code context may be sent to the configured backend for analysis, so remove secrets and private tokens before you run the review.

1. Open a terminal in the root of the Git repository that contains the changes you want to review.

   $ cd ~/src/example-app

   If Codex stops with a trusted-directory error, re-run it from the intended repository root or fix that policy issue separately. Related: How to fix Codex trusted directory error

2. Check the working tree so the review scope is clear before you run Codex.

   $ git status --short
   MM math.py
   ?? helpers.py

   MM means math.py has both staged and unstaged edits. ?? marks an untracked file, which codex review --uncommitted can also inspect.

3. Inspect the staged portion of the diff when you want to confirm what is already in the index.

   $ git diff --cached
   diff --git a/math.py b/math.py
   index 4693ad3..c064e26 100644
   --- a/math.py
   +++ b/math.py
   @@ -1,2 +1,6 @@
    def add(a, b):
        return a + b
   +
   +
   +def divide(a, b):
   +    return a / b

   Skip this step when the staged portion is obvious; Codex still reviews it either way.

4. Inspect the unstaged portion of the diff so the working-tree-only edits are also clear.

   $ git diff
   diff --git a/math.py b/math.py
   index c064e26..63df01e 100644
   --- a/math.py
   +++ b/math.py
   @@ -4,3 +4,8 @@ def add(a, b):
    
    def divide(a, b):
        return a / b
   +
   +
   +def average(values):
   +    total = sum(values)
   +    return total / len(values)

   git diff shows only the unstaged portion. Use git diff --cached for the staged portion and git status --short for untracked files.

5. Run the uncommitted review with Codex.

   $ codex review --uncommitted
   The new `average()` helper rejects generator and other one-pass iterable inputs because it requires `len(values)` after summing. That is a functional regression in the added API, so the patch is not fully correct yet.
   
   Review comment:
   
   - [P2] Avoid `len()` so `average` works with generator inputs - /home/user/projects/example-app/math.py:9-11
     If callers pass a generator expression or any other non-sized iterable (for example, `average(x for x in nums)`), this raises `TypeError` after `sum()` has already consumed the values. That makes the new helper fail for a common Python calling pattern even though the function name does not imply it only accepts sequences.

   The review covers the repository's current working tree state, not a saved commit or branch comparison. If the same files keep changing while you review them, re-run the command after the edits settle.

6. Save the review output when you want to share it or compare it against a later run after more edits.

   $ codex review --uncommitted > codex-uncommitted-review.txt