Agent notes

Choose an agent, refresh its notes, or supply notes from another task.

A coding agent writes short notes for each changed file by default. Configure one with diffsplain config agent NAME, or choose one run with --agent NAME. --no-agent overrides both for a plain review. With no configured or explicit choice, Diffsplain lists usable agents in this order in an interactive terminal: Codex, Claude, Copilot, Cursor, then OpenCode. Each CLI uses its current login. The two per-run options cannot be combined.

A configured default works in non-interactive runs. If that preference is damaged, unsupported, or unavailable, Diffsplain stops instead of discovering or switching to another provider. An explicit --agent or --no-agent does not read the preference, so either can recover a run while you fix or unset it.

Access to a local checkout

Diffsplain chooses one access plan for each note run. The current checkout, --worktree, and --base REF without --head use checkout-read-only. The agent runs in the chosen repo with its normal user settings. It may inspect ignored files, Git history, and symlink targets. Diffsplain tells it not to edit files or run mutating commands. Diffsplain itself does not edit the review target. Agents run under your user permissions, and approval stays with you.

Pull requests, remote branches, and exact local ranges use snapshot-only because they may not map to the live checkout. In that mode, the agent gets only the supplied snapshot. It must not run commands, read other files, use the network, or edit anything. Pass --no-checkout-access to use this mode for any target. It limits both agent notes and review chat to the supplied snapshot.

Codex uses its read-only sandbox. Claude uses permission mode plan. Cursor uses non-interactive Ask mode, its sandbox, --trust, and --workspace. In checkout mode, those agents use the repo as their working folder. Copilot and OpenCode have no proven native read-only mode. Diffsplain warns before either gets checkout access. It does not pass automatic approval flags; approval stays with you.

Cursor Agent needs version 2026.08.11 or newer. Diffsplain runs the signed-in cursor-agent in the user’s home and does not replace HOME. Cursor still contacts its own service. An old CLI or a missing required flag stops Cursor before notes start. Once Diffsplain chooses an agent, a failed check or run ends the command; it does not switch to another agent.

Use a plain diff when you do not want notes:

npx diffsplain --no-agent

Choose an agent or control how it runs:

npx diffsplain \
  --agent codex \
  --model MODEL_NAME \
  --reasoning low \
  --fast \
  --batch-size 2

The default batch size is 12 files. Smaller batches add the first notes to the open page sooner. All supported agents accept --model; only Codex and OpenCode accept --reasoning.

Fast mode is an opt-in provider setting for Codex CLI 0.108.0 or newer and Claude Code 2.1.36 or newer. Pass --fast to apply it to every agent note and Review chat call in the run. Diffsplain checks the selected executable before the first call and stops for an older or unsupported provider. It does not change the chosen model or write a global provider setting. Provider account, model, and entitlement failures are reported as provider errors. --fast cannot be combined with --no-agent.

Ask the review agent

When a review starts with a coding agent, the note pane also has Ask agent. It starts on This file. Choose Review to ask about the whole change. The note tab stays available, so chat does not replace the file note.

Chat threads live only in the local review server’s memory. Reloading the page keeps them while that server runs. Stopping the review clears them. Each thread belongs to one review fingerprint. When the snapshot changes, Diffsplain keeps the old history as stale and asks you to start a new thread before you ask again. A short snapshot read fault keeps visible history, blocks the composer, and shows a recovery message until the review is ready again.

The page shows a running answer, lets you cancel it, and shows Retry only when the server allows a failed or cancelled question to run again. A blocked history can show Retry compaction when the server can compact it; otherwise start a new thread. Moving to another file or scope does not stop work. The page shows a small notice and a cancel control for work still running elsewhere.

Answers use Markdown and carry path and line-range citations. The page renders headings, lists, links, inline and fenced code, block quotes, and line breaks. It does not render raw HTML or images. It also drops unsafe link schemes, including javascript: and data:.

The chat endpoint accepts only the current access token from the local review page. A missing or old token cannot read or change its threads. Review-wide questions respect --exclude rules. A direct question about an excluded file may include that file, but this does not change the rules for review-wide chat.

Agent usage

Open Agent usage on the review page to see separate totals for notes and chat, plus their combined use. Counts cover provider-reported input, output, cache reads, and cache writes for this review. They do not show prices or your account-wide history.

Partial means some calls did not report use; Unavailable means none did. Missing reports do not mean zero tokens. A review that makes no agent calls reports zero input and output tokens. Reusing saved notes does not add the tokens spent creating them in an earlier run.

Exclude files from automatic notes

--exclude PATTERN controls prepared agent context. Repeat gitignore-style rules in the order you pass them. A later rule wins, and ! puts a path back in. Diffsplain tests the current path of a renamed file, not its old path.

Excluded files stay in the local snapshot and page with their full patches. Diffsplain keeps their path, metadata, patch, snippet, and prior note out of automatic agent input. It hides a cached note while the file is excluded and can reuse it only when the file returns with the same patch. If the patch changed while hidden, Diffsplain drops the note. --force does not override an exclusion. If all files are excluded, Diffsplain makes no agent request and keeps the reusable cache state.

This option is not a privacy boundary and does not change checkout access. In checkout-read-only mode, an agent can still inspect the repo. Use it to shape automatic input, not to hide a secret. With --no-agent, Diffsplain still marks matching files in the snapshot, but it starts no agent.

File limits and failed notes

Diffsplain sends a file’s full patch when it is at most 180,000 bytes. For a larger patch, it sends the short patch excerpt shown in the page. If that excerpt still makes the file input larger than 2,000,000 bytes, Diffsplain rejects the file without starting an agent for it.

A bad file note or a failed agent pass does not remove valid notes from other files. Diffsplain publishes each complete note, marks the run as failed, exits with an error, and lists each failed path and reason in meta.failedFiles. It ignores notes for paths outside the requested batch and reports those paths as failures.

Run one note pass

Generate or revise notes without starting the page:

pnpm run summarize -- --repo /path/to/repo --pr 198

The same command accepts branch, worktree, checkout, and exact-range targets. The command reuses complete notes when the file patches, agent, model, reasoning, and access mode still match. Changing those settings starts a new pass even when the patches stay the same. Pass --force to replace every non-excluded note:

pnpm run summarize -- --repo /path/to/repo --pr 198 --force

The presenter follows the same rule, so a cached review opens without a new agent pass. Use npx diffsplain --force when you want new notes.

Fast mode is not part of note cache identity. A run can reuse matching notes created with Fast mode on or off; the current Review metadata still records the mode requested for this run.

Note files

Implicit notes use one file per target in the user cache:

$XDG_CACHE_HOME/diffsplain/summaries/<target-kind>-<target-key>.json

Without XDG_CACHE_HOME, macOS uses ~/Library/Caches/diffsplain/summaries/, Windows uses %LOCALAPPDATA%\diffsplain\summaries\, and other systems use ~/.cache/diffsplain/summaries/. Worktree, checkout, branch, pull request, and range targets each get a distinct keyed file. Pass --summaries FILE to use another path.

Cache control

Saved notes use a short-lived lease while an agent writes them. A reader can still open the last complete notes. If a writer stops, its lease expires and a later run can take over. A writer that loses its lease cannot publish or remove the newer writer’s lease.

See cache location, total size, oldest entry, and active targets:

npx diffsplain cache status

Prune inactive notes by age in days or by total size in bytes. clear --yes removes inactive notes only; it keeps notes under an active lease.

npx diffsplain cache prune --age 30
npx diffsplain cache prune --size 104857600
npx diffsplain cache clear --yes

These commands manage the default note cache, not fetched Git objects or custom --summaries files outside that cache. --cache-dir selects the bare Git cache and does not change the note cache.

Note file format

The file has one change note and notes keyed by file path:

{
  "change": {
    "title": "Short change title",
    "summary": "What the whole change does.",
    "why": "Why the change is needed.",
    "highlights": ["One key result."],
    "risks": ["One point to check."]
  },
  "files": {
    "src/example.ts": {
      "title": "Short file title",
      "what": "What changed in this file.",
      "why": "Why this file had to change.",
      "details": ["One useful detail."],
      "risks": []
    }
  }
}

Missing notes get a plain fallback, so new files still appear at once.

Failed run support records

Support records are off by default. If review setup or agent notes fail, print one JSON record:

npx diffsplain --support-record

Or write it to a file:

npx diffsplain --support-record-file ./diffsplain-support.json

The file contains a new run ID, the agent and its CLI version, Diffsplain and Node.js versions, stage timings, byte counts, and the failed exit state. The stage totals cover cache access, snapshot work, agent calls, note publication, and local page startup. The export uses private file permissions.

The fixed record does not copy repo paths, file paths, prompts, patches, raw agent output, error text, credentials, or environment values. It records byte counts instead of data. A successful run writes no record. The print form goes to standard error, so the diff snapshot output stays unchanged.