diff --git a/PRODUCT.md b/PRODUCT.md index db18c1f..499fcf6 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -20,22 +20,25 @@ Diffsplain runs on a PR and pairs each unified diff with agent-written context a ## Operating Context -Developers run `npx diffsplain` in a Git checkout. With no arguments, it compares the checkout with its default branch. They can also pass a repo path, URL, or `owner/name`, then choose a branch or pull request. Developers move through changed files, search the file list, and expand long patches when needed. The page updates when the diff or agent notes change. +Developers run `npx diffsplain` in a Git checkout. With no target, it shows staged, unstaged, and untracked changes against `HEAD`. They can also pass a repo path, URL, or `owner/name`, then choose a branch or pull request. Developers move through changed files, search the file list, and expand long patches when needed. The page updates when the diff or agent notes change. ## Capabilities and Constraints - Show GitHub pull requests without changing the local checkout. -- Compare the current checkout with its default branch when no target is passed. +- Show staged, unstaged, and untracked changes against `HEAD` when no target is passed. - Accept local paths, Git URLs, and GitHub `owner/name` repo names. - Report local dependency paths, versions, and readiness with `diffsplain doctor`. -- Try Codex, Claude, Copilot, Cursor, then OpenCode when no agent is chosen. +- Use the explicit agent or configured default. With neither set, let an + interactive user choose from usable agents in this order: Codex, Claude, + Copilot, Cursor, then OpenCode. Non-interactive runs need a configured + default, `--agent NAME`, or `--no-agent`. Use Cursor when version 2026.08.11 or newer is installed. Run the signed-in Cursor CLI in the user's home, in non-interactive Ask mode, with `--trust` and `--workspace` pointed at the selected repo for local checkout access or at Diffsplain's temporary snapshot folder for snapshot-only access. Cursor still contacts its service. Once Diffsplain chooses an agent, do not switch agents after a failed check or run. -- Show tracked and untracked worktree changes, exact local ranges, and remote branches as secondary targets. +- Support worktree changes, a base through the working tree, exact local ranges, and remote branches. - Present full or shortened unified diffs, including binary-file metadata. - Pair the whole change and each file with agent-written summaries, reasons, details, and risks. - Keep local review read-only: the app must not change the target repo. diff --git a/README.md b/README.md index 9d23c92..d687132 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,17 @@ Review a Git diff one file at a time, with a short coding agent note beside each patch. -## Use +## 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](docs/content/agent-notes.mdx) +for provider access and login details. + +## Quick start Run from a Git checkout: @@ -11,53 +21,28 @@ Run from a Git checkout: npx diffsplain ``` -The command opens a local page showing staged, unstaged, and untracked changes -against `HEAD`, the same as `--worktree`. It starts at port `2299` and uses the -next free port when needed. You -need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, Cursor, or -OpenCode CLI. Set a default with `diffsplain config agent NAME`, or choose one -run with `--agent NAME`. If neither is set, an interactive terminal lists -usable agents in that order and asks you to choose one. `--no-agent` always -starts a plain review. Cursor Agent must be version 2026.08.11 or newer. It -uses the signed-in Cursor CLI in the user's home and still contacts the Cursor -service. -Pull requests also need a signed-in GitHub CLI. Once Diffsplain chooses an -agent, a failed check or run ends the command; it does not switch agents. - -Common targets: +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: ```sh npx diffsplain --pr 198 npx diffsplain owner/repo --branch feature/my-change -npx diffsplain --worktree npx diffsplain --base BASE_REF npx diffsplain --base BASE_REF --head HEAD_REF ``` -Check Git, the GitHub CLI, and each supported coding agent: - -```sh -npx diffsplain doctor -``` - -Show, set, or unset the default coding agent: - -```sh -npx diffsplain config agent -npx diffsplain config agent claude -npx diffsplain config agent --unset -``` - -An explicit `--agent` overrides the configured default, and `--no-agent` -overrides both. A damaged, unsupported, or unavailable configured agent stops -the command instead of switching providers; use either explicit option as a -recovery path. The two per-run options cannot be combined. +## Full arguments -Arguments: +See the [CLI reference](docs/content/cli.mdx) for details. | Argument | Use | | --- | --- | -| `doctor` | Show dependency paths, versions, and readiness. | +| `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. | @@ -66,10 +51,10 @@ Arguments: | `--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 to the supplied snapshot. | +| `--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`. | +| `--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`. | @@ -77,10 +62,42 @@ Arguments: | `--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`. | -| `--port NUMBER` | Choose an exact local port. The default starts at `2299`. | +| `--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 + +```sh +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 + +```sh +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 ```sh diff --git a/docs/content/agent-notes.mdx b/docs/content/agent-notes.mdx index 99199e8..d9dc646 100644 --- a/docs/content/agent-notes.mdx +++ b/docs/content/agent-notes.mdx @@ -103,6 +103,18 @@ 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 @@ -144,8 +156,10 @@ 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 for files whose patches have not changed. -Pass `--force` to replace every note: +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 @@ -195,6 +209,12 @@ 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 diff --git a/docs/content/cli.mdx b/docs/content/cli.mdx index 1c28ab7..7bf8262 100644 --- a/docs/content/cli.mdx +++ b/docs/content/cli.mdx @@ -137,7 +137,7 @@ 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 affects agent notes only. It does not change the diff or the page. +option limits both agent notes and Review chat. It does not change the diff. ## Exclude files from agent context @@ -192,6 +192,30 @@ 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: + +```sh +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](/agent-notes/#cache-control) for storage details. + ## First run and shutdown Run the setup check through `npx`, which installs the package if needed: @@ -230,7 +254,8 @@ pnpm run doctor | Argument | Use | | --- | --- | -| `doctor` | Show dependency paths, versions, and readiness. | +| `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 path, Git URL, or GitHub repo. | | `--pr NUMBER\|URL` | Review a GitHub pull request. | @@ -240,7 +265,7 @@ pnpm run doctor | `--base REF --head REF` | Review an exact local range. | | `--agent NAME` | Use `codex`, `claude`, `copilot`, `cursor`, or `opencode`. | | `--no-agent` | Show the diff without agent notes. | -| `--no-checkout-access` | Limit agent notes to the supplied snapshot. | +| `--no-checkout-access` | Limit agent notes and Review chat to the supplied snapshot. | | `--exclude PATTERN` | Keep matching files out of automatic agent input. Repeat in gitignore order. | | `--model NAME` | Choose the model used for notes. | | `--reasoning LEVEL` | Set `minimal`, `low`, `medium`, `high`, or `xhigh`. | @@ -261,7 +286,8 @@ pnpm run doctor | `-h`, `--help` | Show command help. | | `-v`, `--version` | Show the installed version. | -Remote repos need `--branch` or `--pr`. You cannot combine two target 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 @@ -282,7 +308,10 @@ 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. When you omit `--agent` and have no configured default in an interactive +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`, diff --git a/docs/content/data.mdx b/docs/content/data.mdx index cf1fc63..6cf0146 100644 --- a/docs/content/data.mdx +++ b/docs/content/data.mdx @@ -69,6 +69,15 @@ 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 diff --git a/docs/content/development.mdx b/docs/content/development.mdx index a6b0714..3657da9 100644 --- a/docs/content/development.mdx +++ b/docs/content/development.mdx @@ -166,8 +166,10 @@ corepack pnpm run cloud:check `cloud:check` runs the clean-checkout gate and the provider/browser tests. Those tests use fake coding providers and a fake browser command. Real Codex, Claude, Copilot, Cursor, OpenCode, GitHub, or browser login is optional and is -needed only for a live integration task. Diffsplain tries Codex, Claude, -Copilot, Cursor, then OpenCode for notes. Cursor Agent 2026.08.11 or newer uses +needed only for a live integration task. Without a configured default or +`--agent`, an interactive terminal lists usable agents in this order: Codex, +Claude, Copilot, Cursor, then OpenCode. You choose one. Non-interactive runs need a configured default, +`--agent NAME`, or `--no-agent`. Cursor Agent 2026.08.11 or newer uses the signed-in Cursor CLI in the user's home. It still contacts the Cursor service. Keep credentials in Codex environment settings, not checked-in rules or scripts. diff --git a/docs/content/index.mdx b/docs/content/index.mdx index e9f6c36..257350e 100644 --- a/docs/content/index.mdx +++ b/docs/content/index.mdx @@ -11,11 +11,15 @@ patch on the left and a short coding agent note on the right. ## Start a review -You need Node.js 22.13 or newer and a signed-in Codex, Claude, Copilot, Cursor, -or OpenCode CLI. Diffsplain tries Codex, Claude, Copilot, Cursor, then OpenCode -when you do not choose one. Cursor Agent must be version 2026.08.11 or newer. -It uses the signed-in Cursor CLI in the user's home. Cursor still contacts its -service. +You need Node.js 22.13 or newer and Git. For agent notes, you also need a +signed-in coding agent CLI. Set a default with `diffsplain config agent NAME` +or choose one run with `--agent NAME`. With neither set, an interactive +terminal lists usable agents in this order: Codex, Claude, Copilot, Cursor, +then OpenCode. You choose one; Diffsplain does not switch agents if it fails. +In scripts, set a default, pass `--agent NAME`, or use `--no-agent` for a plain review. + +Cursor Agent must be version 2026.08.11 or newer. It uses the signed-in Cursor +CLI in the user's home. Cursor still contacts its service. ```sh npx diffsplain diff --git a/docs/content/mobile.mdx b/docs/content/mobile.mdx index 6d55330..93eac26 100644 --- a/docs/content/mobile.mdx +++ b/docs/content/mobile.mdx @@ -126,9 +126,12 @@ Use `http://localhost:2299` in an iOS Simulator. On Android Emulator, use Do not expose a real review through a public tunnel: its diff data may contain private source code. -The packaged `npx diffsplain` server binds to `localhost`. It is for the -computer that starts the review, not for direct phone review. That boundary -keeps the local review local. +The packaged `npx diffsplain` server binds to `localhost` by default. For a +phone on the same trusted network, use `--host 0.0.0.0 --no-browser`, then +replace the host in the printed URL with the computer’s LAN address. Keep the +port and access token in the URL. Anyone with that token and network access +can read the review and use its chat, so share it only with trusted reviewers +and stop the server when done. For cloud browser checks, use BrowserStack Local or an equivalent private tunnel with a non-sensitive fixture. Test current Chrome on Android and Safari diff --git a/site/index.html b/site/index.html index bc30be1..b1f27d7 100644 --- a/site/index.html +++ b/site/index.html @@ -12,7 +12,7 @@ @@ -107,7 +107,7 @@