Assert Local

Review pull requests in Assert, explore logical groups of changes, and share focused review links. No Assert GitHub app installation is required.

Sign in or create an Assert account

Requirements

• Node.js 20.17+, 22.13+, or 23.5+
• GitHub CLI, signed in to your GitHub account
• An Assert account linked to that same GitHub account

Usage

npx assert-local review

To skip the repository picker, pass a repository or a GitHub pull request URL:

npx assert-local review owner/repo
npx assert-local review https://github.com/owner/repo/pull/123

Repositories open their inbox; pull request URLs open that review directly.

The command confirms your account, lets you choose a repository, and opens the review in your browser. It remembers your account confirmation and most recent repository, and keeps the repository inbox up to date while running.

Use --no-open to print the review URL without opening a browser. Press o to reopen the page or Ctrl+C to stop.

Clusters for agents

Discover logical review areas, inspect their changes, and get links to share with reviewers. These commands print their results without prompting or opening a browser.

npx assert-local clusters
npx assert-local clusters --repo example/project --pr 123
npx assert-local clusters https://github.com/example/project/pull/123
npx assert-local cluster error-handling --diff
npx assert-local cluster error-handling --repo example/project --pr 123 --json

clusters shows the first level of the review tree, with titles, descriptions, explicit IDs, file counts, and review links. Use --depth 2 to expand another level or --depth all to show the complete tree. File paths are omitted from the list to keep large reviews readable.

cluster <id> shows a review summary with line-change totals, the five largest changed files, its parent, and immediate subclusters. Use --files to list every changed file. If line-change stats are unavailable, the summary still includes the cluster description, file count, and review link.

cluster <id> --diff prints only the diff on stdout; errors and wait-status messages go to stderr. With --json, the diff remains a field in the JSON result.

Without a target, commands use the current repository and current branch's PR. A different repository requires a PR number. Cluster IDs are exact IDs from the latest clusters result; they may change after new commits or regeneration. Each result includes base/head SHAs, the PR review version, and a version-pinned Assert link. Add --diff to show only the selected cluster's changes, including its subclusters, for that same review version. Diffs are review excerpts with original line coordinates, not necessarily standalone patches to apply. Binary and rename metadata are preserved. Very large comparisons may be unavailable; the command reports an error in that case.

Commands wait up to 60 seconds for usable results. Partial results can be used while smaller subclusters are still generating.

npx assert-local clusters --timeout 2m --wait-until ready
npx assert-local clusters --no-wait --json

--timeout sets how long to wait for clusters and accepts seconds (the default unit), ms, or m. Signing in, finding the PR, and loading its diff may take additional time. --no-wait returns the current status without waiting for generation to complete.

Exit codes: 0 for a successful result (including a pending --no-wait response), 1 for an error, 2 when the wait timeout expires. A timeout returns the last known status and available results, a retry command, and the review URL when known. Cluster generation continues after the CLI stops waiting. If the first request times out, status is explicitly unknown.

--json emits one JSON value on stdout, including structured errors. List output contains the full cluster tree; detail output contains the selected cluster, clusterUrl, line-change stats when available, and optional diff. Text limits such as --depth and the five-file preview do not truncate JSON output. No credentials are printed or saved.