CLI usage

Select a review target and control the local Diffsplain page.

Current checkout

With no target, Diffsplain shows staged, unstaged, and untracked changes against HEAD, the same as --worktree. Already committed changes are excluded.

npx diffsplain

Pull requests

Use a pull request number in the current repo:

npx diffsplain --pr 198

Pass the repo when you run the command elsewhere:

npx diffsplain owner/repo --pr 198
npx diffsplain --repo https://github.com/owner/repo --pr 198

owner/repo is fetched over HTTPS. Diffsplain adds the signed-in GitHub CLI as a Git credential helper for https://github.com remotes only; existing helpers stay in place. gh auth login is enough. You do not need a separate Git HTTPS password.

A full pull request URL carries the repo:

npx diffsplain --pr https://github.com/owner/repo/pull/198

Branches

Compare a branch with the remote default branch:

npx diffsplain --branch feature/my-change
npx diffsplain owner/repo --branch feature/my-change

Choose a different base or remote when needed:

npx diffsplain \
  --repo /path/to/repo \
  --branch feature/my-change \
  --base next \
  --remote upstream

Worktree changes

Use --worktree explicitly to select the default review of tracked and untracked changes against HEAD:

npx diffsplain --worktree

The watcher refreshes the page as the worktree changes. It keeps notes for files whose patches did not change and asks the agent only about new or changed files.

Base through the working tree

Pass --base without --head to compare that exact commit with the current working tree. This includes later commits, staged changes, unstaged changes, and untracked files:

npx diffsplain --base release-1

The page shows the short base ref followed by working tree. If the ref moves, the watcher refreshes the review against its new commit.

Exact local ranges

Pass two refs that exist in the chosen repo:

npx diffsplain \
  --repo /path/to/repo \
  --base BASE_REF \
  --head HEAD_REF

Choose a default agent

Save one default coding agent for future reviews:

npx diffsplain config agent codex

Show or remove it later:

npx diffsplain config agent
npx diffsplain config agent --unset

Selection order is --no-agent, an explicit --agent, then the configured default. The two per-run options cannot be combined. When none is present, Diffsplain keeps the interactive picker. The configured default also works in scripts and other non-interactive runs.

Diffsplain validates a configured agent just like an explicit choice. A damaged preference, unsupported name, or unavailable agent stops the run; it does not fall through to discovery or the picker. Use --agent NAME for a one-run override or --no-agent for a plain review without reading the saved preference.

Agent checkout access

For the current checkout, --worktree, and --base REF without --head, a selected agent uses checkout-read-only access. Its working folder is the chosen repo, so it can inspect ignored files, Git history, and symlink targets when the note needs them. 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 access because their target may not match the live checkout. The agent gets the temporary review input and must use only that input; it must not run commands or read other files.

Pass --no-checkout-access to use snapshot-only access for any target. This option limits both agent notes and Review chat. It does not change the diff.

Exclude files from agent context

Pass --exclude PATTERN to keep matching files out of automatic agent input. You can repeat it:

npx diffsplain \
  --exclude 'private/**' \
  --exclude '!private/keep.txt'

Rules use gitignore-style rules in the order you pass them. A later rule wins. A rule that starts with ! puts a path back in. Diffsplain matches the current path of a renamed file, not its old path.

The local page and snapshot keep every changed file and its full patch. A matching file gets agentExcluded: true. Its path, metadata, patch, snippet, and old note stay out of automatic agent input. Diffsplain hides its cached note while the file is excluded. It can reuse that note when the file returns only if its patch still matches. If the patch changes while excluded, Diffsplain drops that cached note. --force does not override an exclusion.

When all files are excluded, Diffsplain makes no agent request. The local page still shows the diff and reports zero agent notes. Removing or changing rules can show a matching cached note again when its patch has not changed.

This is prepared-context control, not a privacy boundary. It does not change checkout access. A checkout-access agent can inspect files in the repo, so do not use --exclude to hide secrets from an agent.

Check your setup

Run the doctor command to see the separate local review, agent note, and pull request lookup capabilities:

npx diffsplain doctor

The report lists every supported agent, even when it is not installed. It keeps installation, compatibility, authentication, and smoke-test results separate. Missing agents do not stop a plain local review with --no-agent.

Use JSON for setup checks in scripts or cloud jobs:

npx diffsplain doctor --json

The normal check does not send prompts to a provider. --deep runs local --help checks for installed providers after a warning; it does not send a provider prompt.

Saved note cache

Inspect the default note cache, or remove inactive notes:

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

cache and cache status show the cache location, byte count, oldest entry, and active targets. prune --age DAYS removes notes older than that many days. prune --size BYTES removes the oldest notes first until the cache fits the limit or only active notes remain. Pass one limit at a time; both accept non-negative numbers. clear requires --yes. All cleanup keeps notes under an active lease.

These commands manage the default user note cache. They do not remove fetched Git objects or custom --summaries files outside that cache. --cache-dir chooses the bare Git cache for reviews, not the note cache. See Agent notes for storage details.

First run and shutdown

Run the setup check through npx, which installs the package if needed:

npx diffsplain doctor

You can instead run npm install -g diffsplain and then diffsplain doctor. Use --no-agent for a plain local review when no coding agent is ready.

A normal review prints a local URL and tries to open it in your browser. If the browser cannot open, open that URL yourself. The command keeps watching until you press Ctrl+C. It then stops the watcher, local server, and any active note process. Normal shutdown removes temporary page and agent input files. Saved notes remain in the user cache. Fetched Git objects remain in the installed package’s .cache/git folder. See Agent notes and Diff data for paths and cleanup.

Run from source

The diffsplain package script accepts every public command and option:

pnpm run diffsplain -- --worktree
pnpm run diffsplain -- doctor

The doctor command also has a short package script:

pnpm run doctor

Options

Remote repos need --branch or --pr. --pr cannot use --branch, --base, or --head. --branch can use --base, but not --head. --head requires --base. Without --head, local --base compares that exact commit with the live working tree; a branch can also use --base as its remote base. --worktree cannot use another target. --no-agent cannot use --summaries or --fast. Paths passed to --repo, --summaries, --output, --cache-dir, and --codex-bin resolve from the current directory. CODEX_BIN, CLAUDE_BIN, COPILOT_BIN, CURSOR_BIN, and OPENCODE_BIN can select provider binaries. Supported agents accept --model. Only Codex and OpenCode accept --reasoning; its levels are minimal, low, medium, high, and xhigh.

--fast is opt-in and supports Codex CLI 0.108.0 or newer and Claude Code 2.1.36 or newer. Diffsplain checks the selected executable before the first agent call and stops for an older or unsupported provider. It passes the provider’s native Fast setting to every note and Review chat call without changing the selected model or a global provider setting. Account, model, and entitlement errors come from the provider.

--batch-size defaults to 12 and accepts 1 through 50. --jobs defaults to 3 and accepts 1 through 8. --port accepts 0 through 65535. When you omit it, Diffsplain starts at 2299 and increments until it finds a free port. An explicit occupied port stops the command; --port 0 asks the OS for a free port.

When you omit --agent and have no configured default in an interactive terminal, Diffsplain lists the usable choices in this order: Codex, Claude, Copilot, Cursor, then OpenCode. Choose one before the review starts. In a script or other non-interactive run, configure a default, pass --agent NAME, or use --no-agent. Cursor Agent needs version 2026.08.11 or newer. Note batches run in Ask mode with the user’s Cursor login and home. Diffsplain passes --trust and --workspace for its snapshot directory. Cursor still contacts its own service. --agent cursor reports an upgrade or flag error before note generation when the CLI is too old or missing required flags. Once Diffsplain chooses an agent, a failed check or run ends the command; Diffsplain does not switch agents.

For checkout-read-only access, agents run with the chosen repo as their working folder and their normal user settings. Diffsplain keeps approval with you. Copilot and OpenCode do not have a proven native read-only mode, so Diffsplain warns before either uses checkout access. See Agent notes for the provider details.

The two support record options are opt-in and cannot be combined. They include the selected agent, so you cannot use them with --no-agent. See Agent notes for the data contract.