Reviewing & Verifying Changes

Here is the one idea that makes working with Codex safe: the agent writes the code, but you are the merge gate. Codex is fast and usually right — but "usually" is not "always," and the cost of a bad edit slipping into your codebase is far higher than the cost of a thirty-second review. So treat every Codex turn the way a senior engineer treats a junior's pull request: assume good intent, then verify before you trust.

The good news is that Codex is built for exactly this. It does not hide what it does. Every edit it makes and every command it runs is surfaced in a transcript, and it always leaves your changes sitting in the working tree where your normal Git tools can see them. Reviewing is not a bolt-on; it's the second half of the loop.

This lesson is about three habits that turn "the agent did some stuff" into "I know exactly what changed and I trust it":

1. Read the transcript as Codex works — especially before approving anything that edits files or runs commands.
2. Inspect the diff with /diff and, when it matters, get a second opinion with /review.
3. Verify with reality — have Codex run the tests and lint, and use Git as your safety net and rollback path.

Tie-back: This is verification-driven development applied locally. The agent's job isn't done when the code looks right; it's done when a check confirms it is right — and when you've seen the diff that proves it.

As Codex works, it streams a transcript of everything it's doing: the files it reads, the edits it proposes, and the shell commands it wants to run. This is your primary review surface during a turn — before changes are even applied.

Why this matters: depending on your approval mode, Codex will pause and ask before it does something it can't take back (writing files, running a command that leaves the sandbox, anything network- or system-touching). That approval prompt is only as useful as your attention to it. Read what's in front of you before you press approve — especially for destructive steps like rm, a force-push, a database migration, or a command that reaches the network.

The transcript is also how you reconstruct what happened after the fact. Because every action is logged, you can scroll back and answer "wait, what did it just change?" without guessing.

A few mechanics worth knowing:

• Ctrl+T opens (and closes) the transcript overlay so you can scroll the full history of the turn.
• Ctrl+C cancels the current turn if you see it heading somewhere wrong — interrupt is Ctrl+C, not Esc. (Esc Esc edits your previous message; it does not stop a running turn.)
• Codex never silently mutates your repo. If a change landed, it's in the transcript and it's in your working tree.

Gotcha: The approval prompt is a review checkpoint, not a formality. The most common way people get burned is reflexively approving a batch of commands without reading the one destructive line buried in it. Slow down for anything that deletes, pushes, or hits the network.

Once Codex has made edits, /diff is your go-to for reviewing them. It shows the Git diff of your working tree, including files Git isn't tracking yet — and that last part is the detail that saves you.

Why untracked files matter: a plain git diff will not show you a brand-new file Codex just created, because Git doesn't know it exists until you git add it. So if Codex scaffolded a new module, a config file, or a script, a naive git diff hides it — but Codex's /diff surfaces it. You see the complete picture of what the turn produced, additions and modifications alike.

The diff is scrollable right inside the TUI, so you can page through a large change set without leaving Codex or switching to another terminal.

/diff      → scrollable Git diff of the working tree, INCLUDING untracked (new) files

How to actually use it in a review pass:

• Run /diff after any turn that edited code, before you move on or approve a commit.
• Scan for scope creep — files you didn't expect to change are the #1 red flag.
• Check that new files (which git diff would miss) are ones you actually want.
• For anything you're unsure about, escalate to /review (next section) rather than eyeballing it.

/diff shows you what changed. /review tells you what might be wrong with it. Running /review launches a dedicated reviewer that reads a diff you select and reports prioritized, actionable findings — think of it as a second Codex whose only job is to critique the change, not defend it.

This separation is the point. The agent that wrote the code is invested in its own solution; a fresh reviewer reading just the diff is far better at spotting the bug, the missed edge case, or the security regression. It's the generator–critic pattern, built into the CLI.

What you get back is prioritized — the reviewer surfaces the things that matter most first (correctness and security issues ahead of style nits), so you can triage instead of wading through a flat list.

Two related commands round out the review flow:

• /review — ask Codex to review your working tree and report findings over a selected diff.
• /approve — approve one retry of a recent auto-review denial. (Auto-review is an optional posture where a reviewer agent gates risky actions like exfiltration or destructive commands; /approve lets you override a single denial when you've judged it safe.)

A practical rhythm: let Codex finish a unit of work → /diff to see the shape of it → /review to pressure-test it → fix what the reviewer flags → commit. You're using the agent against itself, which is cheaper and faster than waiting for a human reviewer on every small change.

This is the rule that surprises people coming from other agents: Codex has no built-in /undo command. Rollback happens through your normal Git workflow. That's not a missing feature — it's a deliberate design choice. Codex leaves all its changes in your working tree and surfaces every action in the transcript precisely so that Git, the tool you already trust for versioning, is your single source of truth for undoing.

The discipline that makes this painless:

# 1. Commit (or stash) BEFORE you let Codex make big changes — your clean baseline
git add -A && git commit -m "baseline before Codex refactor"

# 2. Let Codex work, then review
#    /diff   → see what changed (incl. new files)
#    /review → get prioritized findings

# 3a. Happy? Commit the result
git add -A && git commit -m "refactor: extract auth middleware"

# 3b. Unhappy? Roll back to your clean baseline
git restore .                 # discard tracked-file edits
git clean -fd                  # remove new (untracked) files Codex created
# or, if you already committed something you want gone:
git reset --hard HEAD~1        # nuke the last commit and its changes

Notice that git restore . alone is not enough to fully undo a Codex turn — it leaves the new files behind. You need git clean -fd to remove untracked files too. (This is the same blind spot /diff saves you from: untracked files are easy to forget.)

The takeaway: commit early and often. A clean commit before a risky task is a one-command rollback after it. Without that baseline, you're reconstructing the old state by hand from the transcript — possible, but tedious.

Human review catches what you can see; self-verification catches what a machine can confirm. The most reliable Codex workflow combines both: you read the diff, and Codex runs the checks. Don't make yourself the only verification step when the agent can run the test suite itself.

The lever is simple — tell Codex, as part of the task, to verify its own work and report results:

"...then run npm test and npm run lint, and show me the output. If anything fails, fix it and re-run until both pass."

Because Codex can execute commands, it will run the suite, read the failures, fix them, and re-run — closing its own loop. The transcript shows you the actual test output, so you're not taking its word for "tests pass"; you can see the green run. This is the single highest-leverage habit in agentic coding: a runnable check turns "looks done" into "is done."

When the review or run is finished and you want to share it — paste findings into a PR description, send a teammate the failing-test summary, or save the reviewer's output — use /copy (or Ctrl+O) to copy the latest completed Codex output to your clipboard. One keystroke, no mouse-selecting a scrolling terminal.