Wiff Review

Wiff Review

wiff is a terminal-first code-review tool. A review lives in a local session that a human browses in the wiff TUI while an agent reads and writes the same session through the wiff command line. The TUI belongs to the human: never launch or drive it. Do all of your work through the wiff subcommands below.

If there is no session to act on, ask the user to start one with wiff first. The exception is when you are the automation that opens reviews (see below).

Opening or refreshing a review from automation

When your job is to trigger reviews rather than review within a session a human opened, create-or-refresh the session for the current changes in one idempotent step:

wiff new --no-tui --if-needed

It creates a session when none exists for these changes, refreshes one in place when the working copy has moved on, and does nothing when it is already current. With no changes and no session yet, it exits non-zero with "no changes to review". By default it reviews the uncommitted working-tree changes; add --from-base to review the whole branch against its trunk instead. Requires --no-tui.

Selecting the session

Every command acts on the active session for the current project by default, so run wiff from inside the checkout being reviewed and you can usually omit any session flag. When the active session is not the one you want, or the project cannot be derived from the working directory, select it explicitly:

wiff session list
wiff render --session 2br8zf30h
wiff comment add --agent --session 2br8zf30h --review --body "..."

• wiff session list prints the sessions for this project and their ids.
• --session <id> targets a specific session instead of the active one.
• --project <name> forces the project when the working directory cannot name it on its own.

Exploring existing code

Not every review is about a change. To annotate existing code, open an explore review: an empty session over the current working copy, to which you add the files you want to comment on.

wiff new --no-tui --explore
wiff explore add src/lib.rs src/parser.rs

• wiff new --explore creates the review with no files yet. Add --no-tui when you are driving it from the command line rather than handing it to a human.
• wiff explore add <PATH>... brings files into the review, each captured at its current state. Re-adding a file already under review does nothing.
• You do not have to add a file before commenting on it: wiff comment add --file F ... on an explore review adds F first when it is not yet present, so --file doubles as the way to bring a file in.

Everything else, reading with wiff render and leaving or revising comments, works the same as on a diff review.

Reading a review

Start here when asked to read a review or to address the comments it holds.

wiff render
wiff render --format json
wiff comment list

• wiff render prints the review as markdown: comments grouped by file, each led by its number (like #3) and showing its author and kind, target location, resolved or outdated state, body, and a fenced snippet of the surrounding code. This is the one command you need to read the review and to pick up the numbers you act on below.
• Each comment has a short review-scoped number, shown as #N, and a long ULID. Every command that names a comment (resolve, verdict, rm, --reply-to) accepts either. Prefer the number: pass it as the bare digits N (a leading # starts a comment in the shell, so write 3, not #3, unless you quote it as '#3'). The ULID stays valid and is the durable identity across sessions.
• When the review has a description (a title and optional body, the same shape as a commit message), wiff render prints it under a ## Description heading and the JSON includes it in a top-level description field. See below to set one.
• wiff render --format json prints the same folded state as JSON for programmatic use. Each comment reports updated_seq and updated_at. To order changes or find the most recent one, use updated_seq, which always advances; updated_at is a display timestamp and, for a comment imported from a forge, can predate an earlier change.
• wiff comment list is an optional compact form: one comment per line, number first, with its status and location, when you want a terse pass without the bodies and snippets.

When you finish addressing a comment, resolve it so the human sees it is done. Pass --agent here too, so the resolution is attributed to you rather than the human:

wiff comment resolve --agent 7