diffgate

# DiffGate

[![npm version](https://img.shields.io/npm/v/diffgate-review?logo=npm)](https://www.npmjs.com/package/diffgate-review)
[![npm downloads](https://img.shields.io/npm/dm/diffgate-review)](https://www.npmjs.com/package/diffgate-review)
[![VS Code Marketplace](https://vsmarketplacebadges.dev/version/srbsa.diffgate-review.svg)](https://marketplace.visualstudio.com/items?itemName=srbsa.diffgate-review)
[![Open VSX](https://img.shields.io/open-vsx/v/srbsa/diffgate-review?logo=eclipseide&label=Open%20VSX)](https://open-vsx.org/extension/srbsa/diffgate-review)
[![License](https://img.shields.io/github/license/srbsa/diffgate)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/srbsa/diffgate?style=social)](https://github.com/srbsa/diffgate)

**A deterministic guardrail your coding agent runs on itself — before the code reaches your disk.**

Every other check fires too late. A review bot needs a PR. A pre-commit hook runs after the agent has finished and moved on. DiffGate is an **agent hook**: your agent calls it over MCP, gets back structured findings in milliseconds for **zero LLM tokens**, and fixes the problem while it still has the context — then the *same engine, same verdict* runs in your editor, your pre-commit hook, and CI. Not a model grading its own homework: the same input always produces the same answer.

It stays quiet by construction. It grades **only the lines that changed** (🟢 merge · 🟡 glance · 🟠 verify), runs your tests only when a change earns it, and blocks only when it's earned — **0 false blocks** on a public, versioned corpus you can rerun yourself with `diffgate bench` ([BENCHMARK.md](BENCHMARK.md)). Everyone claims low noise; this one ships the corpus.

<details>
<summary><b>Why this catches things a scanner doesn't</b> — we measured what agents actually get wrong</summary>

Across local and frontier models: **0%** classic OWASP bugs (SQL injection, XSS, hardcoded secrets) in code written from scratch. But the same frontier model that wrote flawless greenfield code reintroduced security footguns in **13% of edits** — an unguarded recursive merge (prototype pollution), a bare `cors()` (any origin), a path built from request data with no containment check. Editing existing code is most of what an agent does, and the residue lives in the diff, not in the textbook. Rerun it yourself with `diffgate marginal`. [The measurement →](docs/MEASUREMENT.md)

The same shift shows up in third-party maintainability data: [GitClear's 2026 analysis](https://www.gitclear.com/the_ai_code_quality_maintainability_gap) finds block duplication up **81%** since 2023 (40.3 → 73.0 per million changed lines) and cross-file function connectivity down **35%** — agents reinvent code rather than reuse it. That's what the `reinvented-helper` rule is for ([docs/STRUCTURAL-RULES.md](docs/STRUCTURAL-RULES.md)).

</details>

![DiffGate demo: diffgate check on a real repo, mostly green with one orange finding and its reason](https://raw.githubusercontent.com/srbsa/diffgate/main/assets/diffgate.gif)

| Tier | Meaning | What you do | Examples |
|------|---------|-------------|----------|
| 🟢 **Green** | Safe / self-contained | merge freely | comments, local logging |
| 🟡 **Yellow** | Review (soft dependency) | take a look | deprecated APIs, raw SQL, network calls, dependency edits |
| 🟠 **Orange** | High-impact, gate it | verify before merge | schema/migrations, hardcoded secrets, auth/crypto, public-API changes, injection sinks |

---

## Why an agent hook, not another review bot

Every check in the pipeline fires after the code exists, and each one is later than the last:

| | Fires when | Problem |
|---|---|---|
| Review bot (CodeRabbit, Greptile) | a PR exists | the code is finished, defended, and someone is waiting on it |
| Pre-commit hook | you're done and committing | the agent has moved on; you're re-loading context to fix it |
| **DiffGate over MCP** | **the agent is still writing** | it fixes its own output before the code lands |

Being early is not the only thing that matters, though — it has to be *quiet*, or the agent learns to ignore it. Review bots comment after the PR exists; linters and scanners flag everything they see. Neither guarantees the risky line gets discussed: [we scanned 350 merged AI-assisted PRs](docs/posts/the-pr-was-reviewed-the-risky-line-wasnt.md) — of the 109 with flagged AI-attributed changes, only **3** drew public discussion from any human besides the author. DiffGate **decides what deserves your attention, your tests, or a block**, and stays quiet otherwise. That's the whole product:

- **Diff-scoped.** Findings report only on the lines that changed, against the committed baseline — no whole-file noise, no re-litigating code you didn't touch.
- **Tiered triage, not a flat list.** Three tiers route attention: green merges, yellow is a glance, orange is gated.
- **The gate runs *your* tests — selectively.** On an orange change, DiffGate runs your `testCommand` and shows the real exit code and output. Green and yellow pass instantly. The pre-commit hook is fast because tests fire only when a change is genuinely high-impact.
- **Earns the right to block.** Broad cross-language injection findings stay advisory on their own; they escalate to a blocking finding **only when the optional code graph proves the sink is reachable from an untrusted entry point** (an HTTP/event handler). Recall from the rules, the right to block from the graph.
- **Change-impact aware.** With an optional code graph, a finding carries its cross-file blast radius — caller counts, suggested reviewers, untested call sites — and an exported symbol nobody calls is *de-escalated*. Cross-file context makes reviews **quieter**, not louder.
- **Fast.** A review runs in milliseconds on the changed lines — quick enough to sit in the agent and editor inner loop, not only in CI.
- **Provably low-noise.** `diffgate bench` runs a versioned corpus offline: **100% precision / 0 false blocks** on clean changes. Reproduce it yourself — that's the point of shipping the corpus. See [BENCHMARK.md](BENCHMARK.md).

### The measurement is reproducible

The 0% / 13% numbers aren't a marketing line — they come from a scripted experiment (four models from local to frontier, greenfield vs. edit mode, Wilson confidence intervals) that you can rerun with `diffgate marginal`. Methodology, per-model tables, and caveats: [docs/MEASUREMENT.md](docs/MEASUREMENT.md). DiffGate's security rules are tuned to that measured residue, not to maximizing rule count.

---

## Quick start

```bash
npm install -g diffgate-review
cd your-repo
diffgate init                    # auto-detects language + test command, writes .diffgate.json
diffgate check --since=HEAD~20   # see what it catches in your own history — no PR required
diffgate check                   # review your pending changes right now
```

No git history or uncommitted changes yet? See the output on bundled examples first:

```bash
diffgate init --demo   # live scan, no config or git changes needed
```

---

## The surfaces (one shared engine, one verdict)

### 1. In your coding agent (via MCP)

The highest-leverage spot: the agent **self-checks generated code before it's written to disk**, gets back structured findings (zero LLM tokens), and surfaces what it corrected (original + fix + why) instead of silently rewriting. A trustworthy, deterministic self-check is what makes it safe to grant the agent more autonomy.

```bash
# Claude Code — one command:
claude mcp add diffgate -- diffgate mcp

# One-click via Smithery (zero config):
npx @smithery/cli install diffgate-review --client claude

# Cursor — add to MCP settings:
# { "diffgate": { "command": "diffgate", "args": ["mcp"] } }
```

Or one-click in Claude Desktop: download [`diffgate.mcpb`](https://github.com/srbsa/diffgate/releases/latest) and open it. The server also exposes **prompts** and **resources**; see [MCP.md](MCP.md).

### 2. In your editor (VS Code / Cursor)

Inline squiggles on changed lines, hover cards (why · who owns it · quick-fix), a Risk Review tree, a status-bar summary, and **Deep Review** (agentic blast-radius analysis for orange findings). The same verdict you'd get from the CLI, on the diff you're reviewing.

Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=srbsa.diffgate-review) or [Open VSX](https://open-vsx.org/extension/srbsa/diffgate-review) (Cursor / Windsurf / Gitpod).

### 3. On the command line — and in CI

`diffgate check` reviews your diff and exits non-zero on high-impact findings: a pre-commit hook locally, the same gate in your pipeline.

```bash
diffgate install-hook  # adds .git/hooks/pre-commit; only runs tests on 🟠 orange changes
```

The local loop is the wedge — fix while the context is fresh — and the **same engine runs as a PR gate** so the verdict carries to where it's enforced for the whole team. See [docs/TEAM.md](docs/TEAM.md) for the GitHub Action, shared learnings, and org policy packs. CI runs can optionally layer an external scanner (Semgrep) through the same gate for broader language coverage — advisory-only, off by default ([docs/CONFIG.md](docs/CONFIG.md)).

**Common commands:**

```bash
diffgate check                 # review pending changes (the gate)
diffgate check --staged        # staged-only (pre-commit)
diffgate check --since=HEAD~20 # audit recent history, per-commit (see below)
diffgate check --agent         # machine verdict for coding agents
diffgate scan <path>           # analyze files directly (no git needed)
diffgate watch                 # live review as you edit
diffgate guidelines            # review diff against AGENTS.md / CLAUDE.md etc.
diffgate feedback <rule> <f> <l> --dismiss   # suppress a false positive (shared via git)
diffgate mcp                   # start the MCP stdio server
```

**Audit recent AI-authored history.** Point `check` at commits already in your log — each
finding is attributed to a specif