---
title: Diff data
description: Understand the live snapshot, demo data, Git targets, and update cycle.
sidebar:
  order: 4
---

`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:

```sh
npx diffsplain --pr 42
```

See the [CLI guide](/cli/) 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](/agent-notes#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:

```sh
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](/agent-notes/#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:

```sh
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](/cli/#exclude-files-from-agent-context) 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](/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:

```sh
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](/development/) for its source and build command.