All pages
Docs · Right-sidebar surfaces
Review (diff comments)
Availability: macOS (the Review tab) · Linux and Windows (a smaller
Review page, below) · every platform through diff_comment_add / _list /
_flush, including any MCP client.
The Review tab (right sidebar → More ▾) shows the diff you are working on
and lets you leave a note on any line, then hand the whole batch to the agent
as one message. It is the pass that happens before anything is pushed —
gh_pr_comment needs a branch on GitHub and an open pull request, which is
one round trip too late when the code was written two minutes ago by an agent
sitting in the same window.
The diff
The tab shows your uncommitted work (git diff HEAD). When the tree is clean
it falls back to what the branch changes against its base — a fleet worker
commits before it hands work over, so that is the diff you want to read.
Files collapse from their header; binary files say so rather than pretending
to have lines.
The diff follows the window's worktree, so a window pinned to a worktree reviews that worktree.
Notes
Click any line to comment on it. Notes are markdown and reach the model as written. Each note records:
- the file and line, and which side of the diff that number counts on — a note on a removed line is a note about the file as it was;
- the text of the line, which is what lets the note survive the file changing underneath it.
That last part matters more than it sounds. The moment the agent acts on your notes it edits the file, so "line 41" stops meaning what it meant. Every note is re-checked against the file when it is listed or sent, and reports itself as exact, moved to line N, or lost — a note whose line is gone says so and quotes the line it was written against, instead of pointing the model at whatever sits at that number now.
Sending
Send to agent collects every pending note into one message, grouped by file, and hands it to this window's agent as a single turn. Notes already sent stay in the tab greyed out (Show sent notes in the ⋯ menu) so you can see what you already asked for; Clear sent notes drops them.
If the agent is mid-turn, the send is refused and the notes stay pending — they are your work, and a review nobody read is worse than one that waited.
Tools
Agents reach the same notes, which is what makes this work between two agents reviewing each other rather than only between you and one:
| Tool | What it does |
|---|---|
diff_comment_add { file, line, body, side?, scope?, start_line?, context?, diff_identity? } |
Leave a note. side is new (default) or old. context is the line's text; read off disk when you omit it. |
diff_comment_list { file?, scope?, include_sent? } |
The notes, each with where its line is now. |
diff_comment_flush { file?, scope?, diff_identity?, clear? } |
Collect the pending notes into one markdown payload and mark them sent. |
scope says which of the three diffs the note is about: unstaged (the
default — uncommitted work), staged, or branch, what the branch changes
against its base. A note on one means nothing against another, so an invalid
value is refused by name rather than quietly treated as the default, and both
list and flush take it as a filter.
start_line makes a note cover a range; line: 0 is a note about the whole
file, the comment with no single line to sit on. diff_identity records which
diff you were reading, so a note written against an older one is flagged stale
in the payload instead of being dropped — a stale note is still somebody's
comment.
Editing a note you have already sent makes it pending again. The agent was told the old text, and nothing else would ever carry it the new one.
diff_comment_flush returns the payload rather than sending it anywhere.
The usual caller is an agent reading its own review queue, and an agent that
messages itself mid-turn is a loop; the tab's Send to agent button is the
path that delivers a turn.
None of the three ask for approval. They write TRMNLY's own notes, every one is visible and deletable in the tab, and a confirmation click per review comment is exactly the friction that stops anyone reviewing at all. Nothing here touches the repository.
A cloud workspace's agent has the same three tools over that box's own notes file, field for field, so a review left there says the same things in the same words as one left on a Mac.
On Linux and Windows
The sidebar's Review page shows the notes on this project's diff, grouped by file. Each one says where it sits — a line, a range, or the whole file — whether it is still pending or has been sent, and what has become of its anchor when the line has moved or gone. It re-reads when you open it, and every 5 seconds while it is showing, because agents are writing these too.
From the page you can:
- add a note: a path, a line, and what you want to say. Leave the line empty for a note about the whole file.
- Send to agent: marks the pending notes sent and copies the payload, so
you can paste it into the agent you are running. There is no agent loop in
the app on these platforms — the Agent page is a console over
trmnly-core-mcp, and your agent is a CLI in a terminal pane — so the clipboard is the hand-off. An agent that would rather fetch its own notes callsdiff_comment_flushitself, which is the same operation.
Reading the diff is macOS only for now. This page is for seeing the notes and handing them over; a note names its file and line either way. Editing a note, deleting one, and choosing the scope are macOS only too — agents can do all of it on any platform through the tools.
Limits
A project holds 500 notes; a single payload carries 60, and says how many it withheld. Note bodies are capped at 4,000 characters.
Where the notes live
~/Library/Application Support/TRMNLY/review/notes.json on macOS,
$XDG_STATE_HOME/trmnly/review/notes.json on Linux,
%LOCALAPPDATA%\TRMNLY\review\notes.json on Windows — one file, shared by
every process that reads it — and .trmnly/review-notes.json inside a cloud
workspace, which keeps its own. The sidebar and an agent in another process
write the same notes through a cross-process lock, so a note written by a fleet
reviewer shows up in the tab and vice versa. An unreadable file is copied
aside before anything replaces it.