Reviewing changes in a browser

Use sand land NAME PATH --review to review a checkout's diff in your browser, including uncommitted and unpushed changes. The review server runs inside the VM. Your browser displays the diff, and your comments are saved back into the checkout for the agent to read.

The browser interface comes from @self-review/serve, part of the self-review project. sand starts the server, forwards its port, opens your browser, and stops the session when you finish.

Getting a VM that has it

The review tool is included in every base image and runs only when you open a review. There is no installation flag to enable.

If your base image predates the tool, the next sand create updates the base before cloning a new VM. Existing VMs need to be reset from an updated base or replaced to get it.

Opening a review

The VM must be running. Run sand land NAME to list its known checkouts, then use a path from that list:

sand land NAME PATH --review

In the TUI, press l on the VM's tile to open the Landing pane, select a checkout, and press v. The CLI keeps the terminal occupied until the review ends. The TUI marks the row reviewing… and adds the URL when the server is ready.

A review does not require a pushed branch, a configured remote, or gh.

sand chooses the diff's base commit. It uses the parent of the oldest commit absent from all remote-tracking branches in the guest. If it cannot use that parent, it tries the nearest common ancestor with main, master, or the checkout's recorded default branch. If neither method finds a base, the review server uses its default range. The diff also includes uncommitted and untracked files.

Before starting the server, sand prints the base commit, its date, and the number of commits and files to review. For example: everything since 6ac1f20b1e77 (2026-09-18, 5 commits, 12 files). If the range is too large for the review tool, sand stops and names the base commit so you can check it. 2. sand starts the server in the checkout. The server chooses a free port inside the VM. sand makes that port reachable from your workstation (see Reachability), waits for a response, and opens your default browser. 3. The browser displays the checkout's file tree and diff.

If no browser opens, open the printed URL yourself. The review stays running.

You can run multiple CLI reviews at once, on the same VM or different VMs. The TUI runs one review at a time. Trying to review another checkout while a session is running or still shutting down leaves a message in the session log.

Reviewing only part of a branch

By default, sand chooses a base commit for the review and includes all changes since that commit plus any uncommitted work. You can instead review just the commits or staged changes you specify, with precise control over the reviewed range.

From the CLI

Add -- followed by git diff arguments after the --review flag:

sand land NAME PATH --review -- HEAD~2

This reviews the working tree against the last two commits (equivalent to git diff HEAD~2). Other examples:

Command	What it reviews
`sand land NAME PATH --review -- HEAD~2...HEAD`	Only the last two commits, no uncommitted changes
`sand land NAME PATH --review -- --staged`	Only the changes you have staged for commit
`sand land NAME PATH --review -- HEAD~10`	The last ten commits plus uncommitted work

When you provide a range, sand skips its automatic base selection and the file-count guard. A saved review is still carried in, so comments you wrote earlier are there to keep, edit, or drop, and --clean still discards it first.

From the TUI

Press R (capital R) on the Landing pane's checkout row to open a one-line prompt. Type your git diff arguments exactly as you would on the command line:

HEAD~2
HEAD~2...HEAD
--staged

Arguments are split on spaces with no quoting support — git revisions and flags don't need it. Leaving the prompt blank is the same as pressing v and reviews the whole branch with the automatic base selection.

You can cancel the prompt with esc. Once you submit, the review follows the same rules as the v key: it carries in any saved comments and clears the reviewing… state when you finish.

Finishing a review

Leave comments in the browser, then click Finish Review. The server writes review.xml into the checkout inside the VM and exits. The CLI reports the path and returns control of your terminal; the TUI clears the row's reviewing… state.

review written to /home/claude/checkouts/my-repo/review.xml in myvm

Closing the browser tab does not finish the review or save your comments. Comments stay in the page until you submit them. Pressing Ctrl-C in the CLI stops the session without saving them.

In the TUI, leaving the Landing pane does not end the review. You can press esc, open a shell with S, or visit another VM while the browser review stays open. To cancel, return to the checkout's row and press v; the footer reads v cancel review. Quitting sand also stops the review, with a confirmation naming the checkout.

Picking up where you left off

A finished review leaves review.xml in the checkout. When you open another review there, sand loads the saved comments and viewed-file markers:

carrying in the comments already in review.xml
[serve] Resumed 7 comments and 4 viewed files from /home/claude/…/review.xml

You can keep, edit, or delete the comments. Finish Review overwrites the same file with the result.

To discard the saved review and start over:

Where	How
TUI's Landing pane	Press `V` (shift-V) on the checkout's row, labelled `clean review` in the footer.
CLI	Run `sand land NAME PATH --review --clean`.

Both delete review.xml and the accompanying review.guide.xml before starting the server. The TUI asks for confirmation, even if neither file exists. The CLI deletes them without a prompt.

The assistant skills

When provisioning includes an initial project clone, sand installs three self-review skills into that checkout before you start an agent session:

Skill	What it does
`self-review-critique`	Drafts review comments for you to check and edit.
`self-review-guide`	Writes a `review.guide.xml` walkthrough that groups files in reading order.
`self-review-apply`	Reads a finished `review.xml`, prioritises the comments, and makes the changes.

The skills go in .agents/skills/ inside the checkout, with links under .claude/skills/ so Claude Code discovers the same copies. Their instructions refer to schema files under .agents/skills/. They are included in the base image and match the review server's version, so installing them needs no network access.

For a repository you clone later, run the installer inside the VM:

self-review-install-skills /path/to/repository

The command installs or refreshes the skills and Claude Code links, then adds the review artifacts, skill directories, and links to your active global Git excludes file. It leaves a path unchanged when the repository tracks its own copy.

A typical workflow inside the guest:

/self-review-critique --staged     # in the agent: draft a review

Press v in the Landing pane to review and edit those comments, then run:

/self-review-apply review.xml      # in the agent: apply the saved feedback

Skills tracked by your project are kept

If the repository already tracks its own .agents/skills/self-review-* or .claude/skills/self-review-* files in Git, sand leaves those paths unchanged.

Keeping review files out of commits

self-review-install-skills adds review.xml, review.guide.xml, and the three skill directories and their Claude Code links to the guest user's active global Git excludes file. That is ~/.config/git/ignore by default, or the path selected by core.excludesFile. It does not change your project's .gitignore.

Ignore rules do not hide files that Git already tracks.

Feeding it back to the agent

Tell the agent to read review.xml in the checkout, or use /self-review-apply review.xml. The saved feedback is already inside the VM, where the agent is working. You do not need to download or copy it.

Reachability

The server listens on the VM's loopback address, 127.0.0.1. sand makes it reachable at a loopback address on your workstation:

Local Lima automatically forwards the guest port to the same port on your workstation. See Web Servers and Ports.
Remote Lima uses a temporary SSH tunnel from your workstation to the remote host's loopback port, where Lima has forwarded the guest port.
Proxmox uses a temporary SSH tunnel directly to the guest's loopback port.

The guest server and any SSH tunnel stop when you finish or cancel the review. The diff and your comments travel between the VM and your browser. sand does not copy a checkout onto your workstation or push it to a forge.

Other users of a shared remote Lima host can read the review

Lima forwards the review port to 127.0.0.1 on the host running the VM. Anyone logged into that host can access the review while it is open, including the full diff and uncommitted work. The server does not require authentication.

For local Lima, that host is your workstation. Proxmox connects directly to the guest, with no review port on the Proxmox host. If other users of a remote Lima host should not see your work, review it on a host you do not share.

If the review never becomes reachable

Local Lima must use the same port number on the guest and workstation. If another application on your workstation already uses the port the guest selected, forwarding fails and the review times out. sand reports the port. Run the review again to select another port; the review server has no option to request a specific one.

Limits

Automatic resumption uses only the default review.xml path. If you set output-file in .self-review.yaml or ~/.config/self-review/config.yaml, sand does not load the saved review automatically. A clean review also deletes only the default review.xml and review.guide.xml files.

The browser uses self-review's interface, including extra context around changes, image and attachment previews, suggestions, and walkthroughs from review.guide.xml beside the output file.