How to review Claude Code's changes before you commit

Claude Code will happily produce a twelve-file change while you read its running commentary and type "looks good." That commentary is not the change. The transcript shows you what the agent says it did; the diff shows you what it did. The gap between those two is where the bad commits come from, and it widens with every file the agent touches.

The fix is not exotic. It is deciding that nothing gets committed until you have read the diff, and then making the diff readable enough that you actually do it. This guide is that workflow, from the plain-Git floor up. It leans on Hunk for the later steps, so disclosure first: Hunk is built by our team at Modem, MIT-licensed and free.

The floor: git diff before every commit

The zero-install version works today:

git status         # what did the agent touch, and what did it create?
git diff           # tracked modifications
git diff --staged  # whatever is already staged

Note the seam: git diff does not show untracked files, and agent changesets are full of them, because agents create files freely. A new module, a new test, a new config: all invisible to git diff until staged. git status is what catches them, and forgetting that is the most common way an unreviewed file reaches a commit.

This floor is genuinely enough for small changes. Its limits are the reading experience, one long scroll with no navigation, and the fact that it is a snapshot: the agent keeps working and your review goes stale.

Review live while the agent works

Hunk's watch mode turns the snapshot into a standing view:

hunk diff --watch

That opens the working tree as a review UI, one continuous stream of every changed file with a sidebar to jump between them, and reloads automatically as the tree changes. Two properties matter for the agent case. First, hunk diff includes untracked files by default, so the agent's new files land in the review instead of hiding behind git status. Second, because it reloads on its own, you can leave it open for a whole session and glance over as the agent works, rather than reviewing one big pile at the end.

Install is npm i -g hunkdiff or brew install hunk. When you want to review a commit the agent already made instead of the working tree, hunk show opens the latest commit and hunk show HEAD~1 an earlier one.

Put the agent's reasoning beside the code

The transcript-versus-diff gap has a second half: even when you read the diff, the agent's rationale for a hunk lives somewhere else. Hunk closes that with inline annotations, notes attached to specific hunks that render next to the code they explain.

The documented way to wire this up with Claude Code:

1. Open Hunk in one terminal with hunk diff or hunk show.
2. Tell Claude Code to add the skill file returned by hunk skill path.
3. Ask it to use the skill against the live session, for example: "Load the Hunk skill and use it for this review. Run hunk skill path to get the skill path."

The skill teaches the agent to inspect the open review and leave notes on the hunks it wrote, so "why did it change this file" is answered where the question arises. The machinery underneath is still evolving, so treat the skill-based flow above as the stable interface and check the README for current details.

The two-pane workflow

Putting it together, the version we actually run:

1. Pane one: Claude Code, working.
2. Pane two: hunk diff --watch, open for the whole session.
3. When the agent declares a task done, read the review stream top to bottom. [ and ] step through hunks, the sidebar jumps between files, z expands context around anything suspicious.
4. Anything you do not understand, ask the agent about, or have it annotate via the skill.
5. Only then stage and commit.

The habit this builds is the point: the diff, not the transcript, becomes the thing you sign off on. On a laptop screen, a terminal split with the agent on one side and the review on the other is enough; nothing here needs a second monitor.

Jujutsu and Sapling variants

Hunk auto-detects jj and Sapling workspaces, so hunk diff [revset] and hunk show [revset] take native revsets there; no flags needed. Working-copy review under jj is hunk diff, same as Git.

To make Hunk the pager for jj itself, run jj config edit --user and set:

[ui]
pager = ["hunk", "pager"]
diff-formatter = ":git"

For Sapling: sl config -u, then pager = hunk pager under [pager].

Where this stops

An honest boundary: this workflow gets the diff read, and nothing more. Hunk shows you the change; it does not judge it. Tests, CI, and a second human on the pull request still catch what a tired first read misses, and none of this replaces them. And when the agent's output is a visual artifact, a diagram or a mockup rather than code, a diff viewer is the wrong instrument entirely; that problem has its own tooling.

For how Hunk stacks up against delta, difftastic, and the other terminal diff tools, see the comparison guide. Hunk exists because we ship agent-written code at Modem every day and wanted the review step to keep up; it stays MIT and free.