Diffo review

Diffo turns the current git changeset (uncommitted work, or a branch against its base) into a live, readable review in the reviewer's browser. You — the agent that wrote the change — stay attached through the

diffo

CLI: the reviewer's questions and fix requests return into THIS conversation, you act on them with all your context, and your replies land inline in their review.

You do not need diffo installed — invoke it with

npx -y @diffohq/diffo

. If diffo output shows a follow-up command starting with

diffo

, run it as

npx -y @diffohq/diffo …

instead. In restricted subprocess sandboxes or agent harnesses where

npx -y

exits opaquely, use an already-installed copy directly:

node "$(npm root)/@diffohq/diffo/dist/cli.mjs" …

for a local install,

node "$(npm root -g)/@diffohq/diffo/dist/cli.mjs" …

for a global one.

If the protocol goes missing mid-review — a compacted context, a fresh session —

npx -y @diffohq/diffo help agent

reprints the whole loop on one page.

Request

$ARGUMENTS

If the request above is non-empty, the user invoked

/diffo

explicitly — open the review now, following the loop below (a branch name means review against that base:

npx -y @diffohq/diffo --base <branch>

). If it is empty, review the changeset this conversation just produced.

When to use

The user asks to review your changes, or to "open diffo"
You finished a multi-file or subtle change that deserves a human read
The user wants to ask questions about a diff while reading it

The loop

Open the review: run
```
npx -y @diffohq/diffo --no-open
```
from inside the repo. It starts a local server and keeps watching the working tree (your later edits appear live).
```
--no-open
```
matters: an agent never opens a browser at the reviewer — hand them the printed URL instead: end your turn's final message with it, on its own line, the last thing they read (text between tool calls may never be shown, so anywhere else risks losing it), and keep doing that every turn while you stay attached, per the rule below. An unshared URL is an unopened review. The command returns straight away — it leaves a background server watching the repo, so run it in the foreground like any short command and do NOT hold a slot open for it. The review outlives this session; if the command says a server is already watching this repo, one is running — just continue (and still share the URL it printed).
Guide the reviewer in — when the changeset needs it: before handing over the URL, judge whether a cold reader needs orientation (multi-file, structural, or subtle — skip when the diff explains itself). If it does, post ONE comment on the whole changeset — no file, so it anchors there:
```
npx -y @diffohq/diffo comment --message "<what the change does>"
```
Its content: one sentence on what the change does, plus a small ```mermaid diagram if a picture explains the shape better than words (roughly ten nodes). Keep it short — a guide the reviewer skims is a guide that did nothing. Orient reading, never pre-review: no verdicts, nothing is "fine" — the reviewer's independent judgment is the point. If your later edits reshape the changeset, reply to your own guide thread with a short update (it is a thread like any other, so the update lands under it).
Poll for feedback: run
```
npx -y @diffohq/diffo poll
```
. It waits silently (heartbeats only) until the reviewer acts, then prints one JSON payload: a prompt carrying the review threads to act on, with thread ids. Leave it running — never kill it.
- Don't let the poll block the conversation. The reviewer reads at their own pace and talks to you in chat meanwhile — a foreground poll leaves them talking to a wall. Run the poll as a harness-native tracked background task whose completion is guaranteed to resume or notify this same agent (e.g. the harness's tracked background-command facility), and keep answering in chat while it waits. Poll in the foreground ONLY when the harness has no completion-aware background facility.
- Never use
```
nohup
```
  , shell
```
&
```
  ,
```
disown
```
  , redirected fire-and-forget processes, or a detached terminal without a verified callback to keep polling alive. The feedback survives either way — but a payload that reaches a process nobody is listening to never reaches YOU, and the reviewer is left believing you were told. Do not tell the user the review is being monitored unless that wake path is live.
- If the poll is killed or times out anyway, just re-run it. Nothing the reviewer sent is lost: it is held in the review itself, so it outlives the poll, and the server too.
- If the poll prints that it took the review over from another agent session, a second agent is working on this repo. You are attached and the reviewer's feedback comes to you now — nothing is blocked — but say so to the user in your next message, naming the other session, so they know where their feedback is going and can stop the other one if they meant to.
- If the poll returns
```
"status": "superseded"
```
  , another agent session took the review from you. Do not re-poll unless the user asks — you would just take it back and the two of you would trade it. Tell the user instead.
Act on the feedback: threads arrive labeled
```
[issue]
```
(change the code) or
```
[question]
```
(answer in the reply — change nothing). Then reply to each thread, concise and addressed to the reviewer, no preamble:
```
npx -y @diffohq/diffo reply <threadId> --message "<your reply>"
```
(pipe a long reply on stdin instead of --message). Reply as soon as a thread is handled; don't save replies for the end. Code edits are detected automatically — the diff in the browser updates live and the thread flips to addressed. Replies and comments render GitHub-flavored markdown, and a ```mermaid fence renders as a diagram in the review — use one when a flow, sequence, or state picture explains the change better than prose. Keep it small (roughly ten nodes); it renders inside a thread card.
Speak in your own voice, sparingly: you can start comment threads of your own — a potential issue, or context that helps the reviewer read (why a change looks the way it does, where to start). Anchor one to a line (--line), a file, or the whole changeset (no file):
```
npx -y @diffohq/diffo comment [<file>] [--line <line>] --message "<comment>"
```
It is labeled as yours and never counts as the reviewer's feedback until they reply into it — then it is theirs to send. Spend these deliberately: an agent that annotates everything gets skimmed.
Poll again — and only once you're actually done: after handling everything the last payload gave you, run
```
npx -y @diffohq/diffo poll
```
again to keep listening. When the reviewer clicks Finish review, the poll returns their whole batch — queued comments plus honest coverage stats — as one payload; apply it the same way.
Your next poll is read as "I've finished that lot." Every thread from the previous batch that you never replied to stops saying "waiting on the agent" and starts saying no answer, because asking for more work is a statement that you are done with the old. So don't re-poll the instant a payload arrives and then start working — handle the batch first, then poll. If you have deliberately decided not to act on a thread, say so in the thread; a reason is an answer, silence is not.
End politely: when the user moves on or the review is done, run
```
npx -y @diffohq/diffo end
```
to detach. Do not reopen or re-poll a review the reviewer ended unless asked.

Rules

End every turn with the review URL, on its own line, for as long as you are attached — not only the turn that opened it. The review is a page the reviewer returns to across a long conversation, and a link twenty messages back is a link they have to go hunting for. It costs one line, and it is the only thing standing between them and the review. Stop once the review is ended.
One attached agent at a time: the newest poll carries the review. Don't run two polls at once, and don't re-poll to win it back from another session — tell the user which agent is attached and let them decide.
```
npx -y @diffohq/diffo end
```
ends YOUR attachment only. If another session is the attached agent it does nothing, and says so.
Never edit code the reviewer didn't ask about while a review is open — the diff moves under their reading position.
Replies speak to the reviewer, in the thread; don't duplicate them into the chat unless asked.

diffo

NPX Install

Tags

SKILL.md Content

Diffo review

Request

When to use

The loop

Rules