All pages

Close the loop · Lesson 2.1 · 12 min

Review the diff

Read the change, leave notes on lines, and send them back as the next task.

After this lesson you review an agent's change by reading the diff instead of its summary, leave notes on the exact lines that need work, and send them back as one message the agent can act on, before anything is committed.

Time: 12 minutes · Works on: macOS app. Linux and Windows have a smaller Review page; any agent can use the diff_comment_* tools.

The summary is not the change

At the end of a run, the agent tells you what it did. The summary is useful for orientation and useless as a review. It describes what the agent meant to do. The diff is what it did. The two drift apart in predictable ways:

  • Scope creep. You asked for a fix in one function. The diff also renames a helper, reformats a file and bumps a dependency.
  • Weakened checks. A failing assertion was loosened, a test was skipped, or an error is now caught and ignored.
  • Leftovers. Debug logging, commented-out code, a TODO the summary doesn't mention.
  • Wrong place. The fix works, but it's in the caller instead of the function with the bug, so the next caller has the same bug.
  • Things that shouldn't be there at all. A key in a config file, a generated file, an edit outside the project.

Tests catch some of these. None of them show up in a summary that says "Fixed the bug and added a test."

Read in this order

A diff from an agent can be long. Read it in an order that finds the expensive problems first:

  1. The file list. Are these the files you expected? Any file you can't explain is the first question.
  2. The tests. Did any existing assertion change? A new test should be readable before you read the code it tests.
  3. The core change. The few lines that do the actual work. Is it in the right place, and is it the smallest change that works?
  4. Everything else. Renames, formatting, imports. Usually fine. Ask for it to be reverted if it makes the review harder.

Notes are the next task

When you find something, don't fix it yourself and don't open a chat to describe it in prose. Leave a note on the line, written as an instruction:

  • Weak: "hmm, not sure about this."
  • Strong: "Don't catch this error here. Let it reach the handler in server.ts, which already logs and returns a 500."

Then send all the notes in one message. One batch means the agent sees the whole review at once and can make the changes consistently, instead of fixing note one in a way that conflicts with note three.

After the agent acts on your notes, review again. A second pass is usually short, but it's where you catch the fix that introduced something new.

A worked example

You asked for a retry around a flaky network call. The summary says "Added retry with exponential backoff." The diff touches four files.

The file list shows a change to package.json you didn't expect. The diff there adds a retry library. The core change wraps the call, but catches every error, including a 400 response that will never succeed on retry. And the test file has one new test, plus one existing test now marked as skipped.

You leave three notes:

  • On package.json: "No new dependency. A short loop in fetchUser is enough."
  • On the catch line: "Retry only on network errors and 5xx. A 4xx should fail at once."
  • On the skipped test: "Don't skip this. If it fails with the retry, the retry is wrong."

You send them as one message. The agent removes the dependency, narrows the catch, un-skips the test, and the test now fails, showing that 400s were being retried. It fixes that too. Your second review is ten lines long.

Do it in TRMNLY

  1. Open the diff. Show the right sidebar with ⇧⌘\, open More ▾ and choose Review. The tab shows your uncommitted changes. When the tree is clean, it shows what the branch changes against its base instead, which is what you want for a branch a fleet worker committed. In a worktree window, you see that worktree's diff.
  2. Read the file list first. Each file collapses from its header, so collapse the ones you've finished and keep track of where you are.
  3. Leave notes on lines. Click a line and write the note. Notes are Markdown. For a note about a whole file, such as "this file shouldn't be in the change", use Comment on the whole file…. Each note records the side of the diff it's on, so a note on a removed line is about the file as it was.
  4. Send them as one turn. Click Send to agent. Every pending note goes to this window's agent as a single message, grouped by file. If the agent is in the middle of a turn, sending is refused and your notes stay pending. Wait for the turn to end and send again.
  5. Trust the anchors. Once the agent edits the file, line numbers move. Each note remembers the text of its line and reports itself as exact, moved to line N, or lost. A lost note quotes the line it was written on, so the agent never acts on whatever now sits at the old number.
  6. Review the second pass. Sent notes stay in the tab, greyed out. Use the ⋯ menu to Show sent notes while you check that each was handled, then Clear sent notes.
  7. Review before approval, too. With the default Approve posture, every file write waits on an approval card that shows its diff. When one turn writes two or more files, a banner shows how many file changes are pending. Uncheck the files you don't want, then press Approve all, which also denies the unchecked ones. That's a review at the moment it's cheapest, before anything touches disk.
  8. Ask for a quick self-review. Once a conversation has a few messages, the review diff chip above the composer has the agent run git diff and flag bugs, missing edge cases and unfinished work. Treat it as a first pass that finds the obvious, not as your review. The next lesson covers reviewers that aren't the agent that wrote the code.
  9. Let other agents leave notes. The Review tab's notes are also reachable through diff_comment_add, diff_comment_list and diff_comment_flush, which any agent can call, including Claude Code connected over MCP. A reviewer agent writes its findings as notes, they appear in your tab next to yours, and you decide what gets sent. None of these tools ask for approval; they write only TRMNLY's notes, never your repository.
  10. After the pull request. Once the branch is on GitHub, the PR reviewer persona in the gear menu reads a pull request with gh_pr_view and gh_pr_diff and posts inline comments with gh_pr_comment. Use the Review tab first; it's one round trip earlier.

Check yourself

  • You found at least one thing in the diff that the agent's summary didn't mention.
  • You sent three notes in one message, and the agent answered all three.
  • After the agent's edits, your sent notes show as exact or moved, not lost.
  • You can name the order you read a diff in, and why the test file comes before the code.

Go further