How to actually read the code your AI agent wrote

An agent session ends with a cheerful summary and a diff that touches a lot of files. The easy move is to scroll through it, see that it looks reasonable, and merge.

That's skimming, not review. The summary tells you what the agent meant to do; the diff tells you what it actually did, and the two don't always match. This post is the workflow I'd suggest for closing that gap, whether the change came from Claude Code, Codex, Cursor or anything else.

First, decide what you're reading

Agent work usually reaches you in one of three shapes, and each needs a slightly different approach.

A single commit. Good when the agent commits as it goes. git show <sha> gives you the message and the diff together. Read the message first and treat it as a claim you're going to check.

A branch compared against main. This is the usual shape for a longer task. There are two different questions here:

• git diff main...feature (three dots) shows only what changed on the branch since it forked from main. This is almost always what you want for review.
• git diff main feature (two dots or a space) compares the two versions directly, so anything that landed on main in the meantime shows up as well. Useful when you want to know what merging will actually do, confusing if you mistake it for the branch's own changes.

Uncommitted local changes. Common with agents that edit your working tree and leave committing to you. git diff covers tracked files, but it doesn't show new files the agent created. Run git status and look at the untracked list, or git add -N . so new files show up in git diff (undo with git reset). Agents create helper files, scripts and fixtures more often than their summaries mention.

Get the shape before the lines

Before reading any hunk, get an overview:

git diff --stat main...feature
git diff --name-status main...feature

Then ask a few questions:

• Is every file expected? If the task was "fix the date parsing bug" and the lockfile, the CI config and an unrelated component changed, find out why before anything else.
• Where is the weight? One file with 300 changed lines in a "small fix" is worth a look.
• Were tests added, changed, or deleted? Edited assertions deserve more attention than new tests. An agent that can't make a test pass will sometimes change what the test expects.

Read in dependency order, not alphabetical order

Diff tools list files alphabetically, which is rarely the order the change makes sense in. A better order:

1. Types, interfaces, schemas and config: what changed in the contract.
2. The core logic that implements the change.
3. Call sites that were updated to match.
4. Tests last, so you read them knowing what they're supposed to prove.

For each hunk, don't stop at the changed lines. Open the function they live in. A two-line change to a condition can only be judged with the surrounding code in view, and that's exactly the context a diff leaves out.

Check the reasoning, not just the code

Agents produce code that reads fluently, so "does this look like reasonable code?" is the wrong test. Better questions:

• Can you state the cause of the bug in one sentence, and does the change address that cause? A lot of agent fixes treat the symptom: a null check, a retry, a try/except that swallows the error.
• Follow one renamed or re-signed function to its callers. Search the repo for the old name and the new one. Missed call sites, and call sites "fixed" by changing their behavior, are common.
• Look for silent scope creep. Refactors nobody asked for, reformatted files, changed defaults, new dependencies. Each one needs its own justification.
• Check the claims in the summary. If it says "added input validation," find the validation. If it says "all tests pass," run them yourself.
• Watch for confident inventions. Calls to library functions or config options that don't exist, or that exist in a different version. Go to the definition and confirm it's real.

If something doesn't add up, ask the agent why it made that choice. Then verify the answer against the code instead of accepting it. An explanation that cites specific lines is easy to check; one that doesn't is just more text to trust.

Keep the checkpoints small

Review is much easier when the units are small. A few habits help:

• Ask the agent to commit after each logical step, with a message that says what and why.
• Review between steps rather than at the end of a two-hour session.
• When a diff is too big to read properly, say so: ask for it to be split, or reset and redo it in smaller pieces. A change you can't review is a change you don't understand yet.

Where Yenpo fits

Yenpo is the Mac app I made for the reading step above. To be clear about what it is and isn't:

• It opens the three shapes from this post: a single commit, a branch compared against main (only the changes since the fork point, or a direct compare of the two versions), and uncommitted local changes, including untracked new files. Diffs are inline.
• Go to definition and find references come from local language servers (Swift, Rust, C/C++/Objective-C, Python, JS/TS, Go). They aren't bundled: Swift and the C family use Xcode's, the others use what's on your PATH, and rust-analyzer has a one-click install. Go to definition works right in the diff for uncommitted changes; for commits and branches, you open the file in the editor. There's also full-text search.
• There's an optional AI Reader that uses your own provider. It shows which files it read and what it searched, and the file:line references in its answers are clickable, so you can check them against the code. The AI Reader is read-only by default. Allow Edits applies only to the next message you send to the AI Reader, then switches back to read-only.
• It's built for reading changes, not for writing code or driving your agent, and it doesn't integrate with Claude Code, Codex, Cursor or GitHub. It reads your local git repo. No Yenpo account or telemetry; it only goes online for your own AI provider, an optional daily update check, and downloads you start yourself.
• It needs macOS 14 or later.

You don't need it to follow this workflow. git diff, your editor and some discipline get you most of the way. If you want to try it: yenpo.app.

The short version

• Know which shape you're reading: a commit, a branch since its fork point, or local changes including untracked files.
• Look at the file list and stats before the lines.
• Read in dependency order, with the surrounding code open.
• Treat the agent's summary and explanations as claims, and check them against the code.
• Keep the steps small enough that you can actually read them.

I'd like to hear how others handle this, especially on large agent diffs. What do you check first?

Drafted with AI assistance and reviewed by me.