Skip to main content
The Git Diff viewer shows what an agent changed in its working tree. You can review those changes the way you would review a colleague’s pull request: pin a comment to a line or a range of lines, collect several comments across files, and send them back to the agent as one review. The Git Diff viewer with a comment pinned to lines 12-14 and two comments in the Review tray Each comment the agent receives names the file and lines it is about (for example src/app.ts:12-14) and quotes the diff hunk it was left on. The agent can find the code without guessing, even after the file has moved on.

Open the diff

  • Press Cmd+Shift+D / Ctrl+Shift+D for the agent you are looking at.
  • Right-click an agent in the Left Bar and pick View Git Diff for that agent.
  • Hover the git status widget beside the branch pill and open the full diff from there.
A review goes to the agent the diff belongs to: the one you right-clicked, or the one you are looking at. The agent’s name is in the viewer header and on the send button. Terminal-only agents have no conversation, so their diff opens without review comments.

Leave a comment

With the mouse:
  1. Click a line number. A comment box opens under that line.
  2. For a range, press on the first line number and drag to the last, or click one line number and Shift+click another.
  3. Type your comment (Markdown is fine) and press Cmd+Enter / Ctrl+Enter, or click Add Comment.
With the keyboard:
  1. Press Down or Up to move a line cursor through the file. The first press lands on the first changed line.
  2. Hold Shift with Down or Up to extend the cursor into a range.
  3. Press C to open a comment box on the selected lines.
  4. Press Cmd+Enter / Ctrl+Enter to save it.
A range stays inside one hunk: dragging or extending past the edge of a hunk stops at that edge. Unified and side-by-side views both work. In side-by-side view, picking an unchanged line in the left column numbers it as in the previous version of the file.

Line numbers

Line numbers refer to the current version of the file. A comment on removed lines only can’t use those numbers, because the lines no longer exist, so it numbers them as in the previous version and says so: src/app.ts:7 (previous version). For a renamed file, those previous-version numbers are given with the file’s previous name.

Collect the review

Saved comments appear under the last line they cover. Every pending comment, across every file in the diff, is listed in the Review tray at the bottom of the viewer. Click a comment in the tray to jump to its file and edit it, or click the trash icon to remove it. Comments stay until you send or discard them:
  • Switching between file tabs in the viewer keeps them, including a comment you are still typing.
  • Closing the viewer keeps them, and a comment you were still typing. Open the diff for the same repository again and they are back, with the unfinished comment open on its lines. If those lines changed in the meantime, its text is kept in the tray as an outdated comment.
  • Quitting Maestro clears them.
Each repository has its own review. For an agent on an SSH remote, the repository is the remote host plus the path, so the same path on two hosts never shares one.

Outdated comments

The agent may change the code while your review is pending. When you reopen the diff, Maestro checks each comment against it. If the lines a comment covers moved, changed, or left the diff, the comment is marked Outdated in the tray and is no longer drawn on a line. An outdated comment is never sent, because its path:lines would point the agent at the wrong code. It stays in the tray so you can read it, remove it, or write it again on the new lines. The tray header counts them, and when every comment is outdated the send actions are turned off.

Send the review

The tray has three actions: If the review can’t be delivered (the agent was removed, or has no AI tab), Maestro says so and keeps your comments. After a send, only outdated comments stay behind.

What the agent receives

The review arrives as one message. For two comments it looks like this:
A long hunk is trimmed to the commented lines plus five lines on each side, with ... where lines were left out. If the diff was taken somewhere other than the agent’s working directory (for example, the agent’s terminal is in another repository), the review says which directory the changes are in, so the agent does not edit matching files in the wrong repository.

Shortcuts

These work while the Git Diff viewer is open over an agent that can take a review. The viewer’s other keys still apply: Enter switches between unified and side-by-side view, and Cmd+[ / Cmd+] (Ctrl+[ / Ctrl+]) move between files.

For agents and scripts

Every action in the tray has a maestro-cli verb, working on the same pending comments the viewer shows: add, edit, remove, discard (clear), send, and edit in composer (send --compose). A comment added or edited from the CLI appears in an open viewer’s tray, and send runs the same code as Send Review. As in the tray, an outdated comment cannot be edited; remove it and add a new one.
send delivers without moving your view unless you pass --focus. See CLI: Reviewing an Agent’s Diff.