Diff data

Understand the live snapshot, demo data, Git targets, and update cycle.

npx diffsplain gives each running command its own temporary snapshot and serves it on a local page. This keeps two open reviews from reading or replacing each other’s data.

Review a pull request:

npx diffsplain --pr 42

See the CLI guide for all review commands.

Review targets

Target	Comparison	Workspace changes	Network and cache	Refresh
Current checkout (no target flag), or `--worktree`	`HEAD` through the current worktree	Staged, unstaged, and untracked files; excludes prior commits	No Git network	Local state every two seconds
`--base REF`	The resolved base commit through the current worktree	Later commits, staged, unstaged, and untracked files	No Git network	Local state every two seconds
`--base REF --head REF`	The two resolved commit trees	None	No Git network	Moved refs every two seconds
`--branch NAME`	Remote base/head merge base through the remote branch head	None	Fetches into the Diffsplain bare cache	Remote data every 30 seconds
`--pr NUMBER`	Pull request base/head merge base through the pull request head	None	Reads pull request data with `gh`, then fetches into the bare cache	Remote data every 30 seconds

Snapshot contents

The JSON file has:

a content version and generation time;
repo, base, head, branch, and target data;
one summary for the whole change;
a list of changed files.

Each file records its path, status, line counts, full unified patch, short snippet, binary state, and agent note. agentExcluded: true marks a file that stays out of automatic agent input. The snapshot still keeps that file and its full patch. The writer gives each snapshot a content hash and replaces the file only when its contents change.

An opt-in failed-run support record is separate from this snapshot. It keeps only fixed version fields, numeric timings and byte counts, a run ID, and the exit state. It does not copy snapshot fields, patches, notes, paths, raw agent output, credentials, or environment values. See failed run support records.

repo.base and repo.head hold the exact commits used for the diff. repo.target records the target kind, remote refs, remote tips, and merge base.

Watch for changes

Diffsplain checks Git state and the note file every two seconds while a review is open:

npx diffsplain --worktree

npx diffsplain --worktree starts the watcher and local page together. The page listens for live events and polls the JSON every 1.5 seconds when the event stream drops. Each refresh ignores older requests that finish late. A bad or missing refresh leaves the last valid snapshot and selected file on screen while the page reconnects.

In watch mode, remote pull requests and branches update every 30 seconds.

Agent usage

The served snapshot includes usage.agentNotes, usage.reviewChat, and usage.combined. Each reports its call count and whether token counts are complete, partial, or unavailable. Counts cover provider-reported input, output, cache reads, and cache writes for the current review. They do not include account-wide history or the past work that produced cached notes. See Agent usage.

Chat state and refresh

When a review has a selected coding agent, the local server also keeps its chat threads in memory. The browser reads them from /api/chat with the active access token in the page URL. The server sends a chat event when a thread changes, while normal update events still refresh the diff snapshot.

A thread records its review fingerprint. If a new snapshot has a different fingerprint, Diffsplain marks that thread stale and keeps it as prior history. It does not send another question with the old evidence. Start a new thread to ask against the new review. File navigation and switching between file and review scopes do not cancel a running answer.

A missing or bad snapshot can leave prior chat history on screen. The page blocks new questions until the server reads a complete current snapshot again. Chat state is not part of diff-data.json, the note cache, or support records. It ends when the local review server stops.

Base through the working tree

Pass --base REF without --head to compare one exact base commit with the live working tree:

npx diffsplain --base release-1

Diffsplain resolves REF to a commit before it starts the review. The snapshot records that ref and commit as base-worktree, then records the current HEAD or WORKTREE as its head. It does not add source or comparison links, because the working tree has no remote commit. The watcher refreshes if the base ref, HEAD, tracked changes, untracked content, or saved notes change.

Agent data and cleanup

The agent receives target and change metadata, selected patches or excerpts, and reusable notes. Files marked agentExcluded stay in the local snapshot, but automatic input omits their path, metadata, patch, snippet, and old note. Its completed snapshot records the plan in notes.accessMode: checkout-read-only or snapshot-only.

The snapshot records the current Fast mode request in notes.fast. This is run metadata, not note cache identity, so unchanged notes can be reused when Fast mode is enabled or disabled.

--exclude PATTERN sets that prepared context. It does not remove a local file or patch, change checkout access, or provide a privacy boundary. See the CLI guide for ordered rules and cache behavior.

The current checkout, --worktree, and --base REF without --head use checkout-read-only access. The agent uses the chosen repo as its working folder and may inspect ignored files, Git history, and symlink targets. The prompt forbids edits and mutating commands, and approval stays with the user.

Pull requests, remote branches, and exact local ranges use snapshot-only access. The agent runs from a temporary input folder and may use only the supplied snapshot. The prompt tells it not to run commands or read other files. Pass --no-checkout-access to use this plan for any target.

By default, each run uses a temporary snapshot, which normal shutdown removes. Agent input files are also temporary. If you pass --output FILE, that snapshot stays at the chosen path until you delete it.

Notes for every target persist in the platform user cache described in Agent notes. Fetched Git objects use the installed package’s .cache/git folder by default. --summaries FILE and --cache-dir PATH put this state at paths you choose. Delete both default locations, or the chosen files and folders, when you no longer need them.

Remote targets

Pull requests and remote branches do not change the current checkout:

npx diffsplain --branch topic --base main --remote origin

Diffsplain fetches Git objects into its bare cache, finds the merge base, and reads the diff there. It does not change the chosen checkout, index, refs, or FETCH_HEAD.

Demo data

The landing page uses checked-in sample data. See the development guide for its source and build command.