Running a review

/deltaview feat/my-branch
/deltaview 3f2c1ab

Deltaview always reviews a branch against its target: the diff between the head and its merge-base with the target branch. A branch name uses the branch tip as the head; a commit hash uses that commit, i.e. the branch as it stood then. If the diff is empty, for example because the commit is already on the target, it says so and stops.

Which commits and target

If the branch has an open PR, the PR's current tip is fetched and reviewed, not a possibly stale local branch. Fork PRs are fetched the way gh pr checkout does.
If the ref isn't local, it's fetched from origin.
The target is the PR's base branch, else the repo's default branch (from gh or origin/HEAD), else main or master. If none fit, Deltaview asks.

What happens

Checkout. The ref is checked out in a temporary git worktree, so your working copy is untouched. Untracked .env* files are copied into it byte for byte, without being read.
Install. Dependencies install with the package manager your lockfile implies (npm, pnpm, yarn, bun) or the build file's usual install. A failed install is shown and the review stops.
Env check. New env vars are detected from .env.example (and .env.sample, .env.template) and new process.env.X / import.meta.env.X references in the diff. If there are any, you're asked to add them to your .env before the app starts.
Tests. Your test command runs and the result is recorded. Failing tests don't block the review.
Analyse and anchor. Claude groups every hunk into items, starts your dev server, and finds the element each item affects. See How it works.
Review. A local proxy starts in front of your dev server and the review opens in a new Chrome tab. The Deltaview bar sits bottom-left. If any item is on screen, you're asked whether to also start the base version for a side-by-side Before ⇄ after view. That takes a second worktree, install and dev server on another port; if it fails, the review continues without it.
Finish. Clicking Finish review posts the review and the agent reports the result: the review URL, counts per decision, the test result and the manifest path. The dev server is stopped and the worktree removed, along with the base version's if one was started.

If the app needs a login

The agent never logs in for you. If the app shows a login page, log in yourself in that tab, then continue.

Resuming

Decisions are saved to the manifest the moment you make them. If you stop before finishing, run /deltaview on the same ref again: when the head commit is unchanged, the review resumes with the same items and your decisions kept. Analysis and anchoring are skipped, but the app and proxy start again.

If the branch has new commits, a fresh review starts that builds on the earlier one. A finished review is never resumed.

Fixing and re-reviewing

/deltaview:fix feat/my-branch

/deltaview:fix reads the newest review of the branch (or the manifest path you pass, or the newest review of any branch when you pass nothing) and works through its rejected and commented items, rejections first, using each item's hunks, reason and the line it was anchored on. It:

checks out the reviewed branch in your working copy, after asking, and stops if you have uncommitted changes;
warns when the branch has moved on since the review, and checks each item against the current code;
makes the smallest change each reason asks for. A comment that is a question rather than a change request is noted, not acted on, and an unclear reason is asked about instead of guessed;
runs the test command and reports each item as fixed, not changed, or needing your input;
commits only if you say so, and never pushes.

Once the fixes are pushed, run /deltaview <branch> again. Claude keeps the earlier review's grouping, titles and selectors for code that hasn't changed. Items whose edits are byte-identical to an item in the last review get its decision back, marked carried over; the rest are marked changed since your last review.

Ground rules

The agent follows these on every run:

In your app it only navigates by URL, scrolls and reads. It never clicks, types or submits.
It never modifies your working copy. The only writes to your checkout are under .deltaview/ and one .deltaview/ line in .git/info/exclude.
It never reads, prints or edits .env* files; it only copies them.
It doesn't try to fix a failing install, app start or test run. It reports and stops, or continues.