--- title: Agent notes description: Choose an agent, refresh its notes, or supply notes from another task. sidebar: order: 3 --- 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: ```sh npx diffsplain --no-agent ``` Choose an agent or control how it runs: ```sh 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: ```sh 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: ```sh 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: ```text $XDG_CACHE_HOME/diffsplain/summaries/-.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: ```sh 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. ```sh 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: ```json { "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: ```sh npx diffsplain --support-record ``` Or write it to a file: ```sh 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.