Diffsplain

Review a Git diff one file at a time, with a short coding agent note beside each patch.

Prerequisites

• Node.js 22.13 or newer and Git.
• For agent notes: a signed-in Codex, Claude, Copilot, Cursor, or OpenCode CLI. Cursor Agent requires version 2026.08.11 or newer.
• For pull requests: a signed-in GitHub CLI (gh auth login).

Check your setup with npx diffsplain doctor. See Agent notes for provider access and login details.

Quick start

Run from a Git checkout:

npx diffsplain

Choose an agent when prompted, or use --no-agent for a plain diff. The page shows staged, unstaged, and untracked changes against HEAD and updates as files change. It starts at port 2299, using the next free port if needed. Press Ctrl-C to stop.

Other targets:

npx diffsplain --pr 198
npx diffsplain owner/repo --branch feature/my-change
npx diffsplain --base BASE_REF
npx diffsplain --base BASE_REF --head HEAD_REF

Full arguments

See the CLI reference for details.

Argument	Use
doctor [--json] [--deep]	Check local review, agent note, and pull request capabilities.
cache [status|prune --age DAYS|prune --size BYTES|clear --yes]	Inspect or remove inactive saved notes.
config agent [NAME|--unset]	Show, set, or unset the default coding agent.
REPO, --repo PATH|URL|OWNER/REPO	Select a local or remote repo.
--pr NUMBER|URL	Review a GitHub pull request.
--branch NAME	Compare a remote branch with its default branch.
--worktree	Review tracked and untracked changes against HEAD.
--base REF	Compare that exact commit with the live working tree.
--base REF --head REF	Review an exact local range.
--agent NAME, --no-agent	Choose a coding agent, or show a plain diff.
--no-checkout-access	Limit agent notes and Review chat to the supplied snapshot.
--exclude PATTERN	Keep matching files out of automatic agent input. Repeat rules in gitignore order; the diff still shows them.
--model NAME	Choose the model used for notes.
--reasoning LEVEL	Set minimal, low, medium, high, or xhigh for Codex or OpenCode.
--fast	Enable provider Fast mode for agent notes and Review chat.
--batch-size COUNT	Set the most files per agent pass. The default is 12; large patches use smaller batches.
--jobs COUNT	Set agent passes to run at once. The default is 3.
--force	Regenerate all agent notes instead of using cached notes.
--support-record	Print a safe JSON record if the review fails.
--support-record-file FILE	Write one safe JSON record if the review fails.
--remote NAME|URL	Choose the Git remote. The default is origin.
--summaries FILE	Choose the saved agent-note file.
--output FILE	Choose a live snapshot file that remains after shutdown.
--cache-dir PATH	Choose the bare Git cache folder.
--codex-bin PATH	Choose the Codex executable.
--port NUMBER	Choose a port; 0 asks the OS for a free port. The default starts at 2299.
--host ADDRESS	Choose the page bind address. The default is localhost.
--no-browser	Print the page URL without opening a browser.
-h, --help	Show command help.
-v, --version	Show the installed version.

Default agent

npx diffsplain config agent          # Show the default
npx diffsplain config agent claude   # Set it
npx diffsplain config agent --unset  # Remove it

Use --agent NAME to override the default or --no-agent for a plain diff; the two flags cannot be combined. Without a choice, an interactive terminal asks you to pick a usable agent. Scripts need a default or one of these flags. A failed agent check or run stops the command; Diffsplain does not switch agents.

Saved notes

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

Cleanup keeps notes in active use. These commands manage the default note cache, not the bare Git cache selected by --cache-dir.

Local development

corepack enable
corepack pnpm run setup
corepack pnpm run dev

Run the public CLI from this checkout:

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

Install Chromium once, then run the checks:

corepack pnpm run test:browser:install
corepack pnpm run check
corepack pnpm run test:browser

Run the Blume docs:

corepack pnpm run docs:dev

More guides are in docs/.