Documentation
SuperDiffs reviews pull requests on GitHub. It is tuned to post few comments and be right about them, which is a different product from one tuned to find everything.
What it does to a pull request
When a pull request is opened, or a commit is pushed to one, SuperDiffs reads the diff, checks out the repository in an isolated sandbox, runs the analysers your configuration enables, asks a model to find defects, and then tries hard to disprove each one before it says anything. What survives is posted as inline review comments, plus a single summary comment it edits in place rather than re-posting.
Nothing is posted at all on a lot of pull requests. That is the intended behaviour, not a failure: a two-line configuration change with nothing wrong with it should produce silence.
How a review is produced
Every review runs the same stages, and every stage can be replayed from a stored trace.
| Stage | What happens |
|---|---|
| Triage | Classify each changed file, drop the ones nobody wants reviewed (lockfiles, generated output, vendored trees, minified bundles), group the rest by subsystem, and pick an effort level. |
| Find | One to five independent passes over the numbered diff, depending on profile. Each pass sees the same context in the same order, so the passes disagree about findings rather than about inputs. |
| Vote | Findings are matched across passes by fingerprint. Something only one pass out of several saw is treated as a guess and dropped. |
| Verify | Each survivor must be grounded in evidence that actually appears in the code, and may be probed in the sandbox — read the neighbouring file, grep for the caller, check whether the guard exists elsewhere. Findings that fail are dropped, not downgraded. |
| Dedupe | Anything already raised, already resolved, or already said by a human reviewer is removed. This is what stops the second push from repeating the first review. |
| Rank | Sort by severity and confidence, apply your threshold and comment cap, collapse nits into one section, then post. |
What lands on the pull request
- Inline comments anchored to a specific line, each with a one-sentence claim, a concrete failure scenario, and — where we can offer one — a suggested patch you can commit from the GitHub UI.
- One summary comment, edited in place on every re-review, with the file walkthrough and the counts by severity.
- A check run reporting status and linking the review, so a branch protection rule can require it if you want one.
- A collapsed nitpicks section, when the profile allows nits at all. It is the first thing dropped when a review exceeds its comment budget.
The two dials
Almost every “it says too much” or “it missed something” question is answered by two settings: profile controls how hard we think, and severity_threshold controls what gets posted. They are orthogonal on purpose — you can think hard and say little.
| Profile | Find passes | Effort | Posts | Comment cap |
|---|---|---|---|---|
quiet | 1 | low | major and above | 10 |
balanced | 1 | medium | minor and above | 20 |
thorough | 3 | high | nit and above | 40 |
Both live in .superdiffs.yaml. See configuration for the full file.
Where to go next
Quickstart
Install the app and get your first review, in about five minutes.
Commands
Every `@superdiffs` command, and who is allowed to run it.
Configuration
The `.superdiffs.yaml` file: every key, its default, and how layers merge.
Limits & skips
What we refuse to review, what we cap, and how each is reported.
Security & trust
The isolation boundary, the token scope, and the injection rules.
Self-hosting
What runs in your infrastructure, what it costs you to operate.