LeanGate

AI coding agents write code that runs but doesn't belong in your codebase. LeanGate is the referee inside the agent's loop.

It's an MCP server plus a pair of hooks, so it works with Claude Code, Codex, Cursor, or any other MCP client. Before the agent writes anything, it checks whether the repo already has what the agent is about to build. Right after every edit, it tells the agent what's wrong with the code it just wrote. And when the agent tries to finish, it blocks until the blocking issues are fixed. Generation and judgment run on NVIDIA Nemotron through Nebius Token Factory.

leangates.com · License: MIT · Python 3.11+

Checks Python codebases today; TypeScript and JavaScript are next. Changed files in other languages are listed in the report as not checked, never passed silently.

Claude Code, one step (needs uv): the MCP server and all four hooks.

/plugin marketplace add lambdabypi/leangate
/plugin install leangate@leangate

Anything else: pip install "leangate[providers]" (or uvx leangate mcp to run the MCP server with no install), then see Connect a coding agent. Put provider keys in ~/.leangate/.env.

Why

I gave two Nemotron models, Nano and Super, twelve tasks on Zulip, a real production Django app with about 2,000 Python files. Without LeanGate, three things kept happening.

1. They didn't know the codebase. Seven of the tasks asked for something Zulip already has a helper for, and both models rewrote all seven from scratch. One of them came out at 57 lines when a single call to append_url_query_string does the job.

2. They did what the prompt pushed them toward. shell=True with a name an admin types into a form, SQL built with an f-string, pickle.load on a path the client sends, verify=False. Five safety tasks, five times the problem shipped.

3. They invented internal APIs. Nano imported zerver.http, zerver.lib.log and zerver.version. None of those modules exist, so those files crash the moment they're imported.

None of this trips a normal linter. The code parses, it reads fine in a diff, and a reviewer skimming forty agent-written files a day isn't going to catch an invented import.

With LeanGate in the loop (check_reuse before writing, one round of the per-edit hook's findings after), the same models did this:

After one round of feedback the injection, TLS and shell problems were gone. What remained: Nano still loaded pickle in one task (the one block left), and Nemotron's "missing validation" findings, which never block on their own, stayed on the file-download task (both models) and the SQL task (Nano). Each model's whole 24-task run, both conditions, coding agent plus LeanGate, cost $0.018 (Nano) and $0.030 (Super). It's twelve tasks with one run each, so read it as direction rather than a precise number. The method, raw output and caveats are in bench/RESULTS.md.

And the bigger model didn't close the gap. Super missed the same seven helpers Nano did.

A full coding agent closes most of it. Run the same way on 12 more public repos with Claude Code (Haiku 5.5), which searches the repo and refuses most unsafe shortcuts on its own, LeanGate made no difference to reuse (10 of 12 both ways). On safety it stopped the two unsafe changes Claude did write (eval of user input, verify=False) and handed them back to the user with the safe version, where Claude alone reported them as done. It also exposed false positives and a hole: the agent could waive its own security findings. That's closed now (only a person can waive one, below): bench/RESULTS_claude.md.

Related MCP server: CodePeel MCP Server

Try it

After setup (no keys needed: every provider has an offline fallback):

python demo/run_demo.py      # clean repo → agent's bloated change → hook blocks → fix → minimize → numbers card
leangate verify              # check your own working tree (exit 1 when blocked)
leangate reuse "parse a unified diff"
leangate dep requests --purpose "HTTP calls"
leangate-service             # web playground at http://127.0.0.1:8000/
pytest                       # the full suite (about 240 tests), fully offline

Demo output (offline mode, abridged):

hook decision: block  (1.76s)
  pyproject.toml:5 unneeded_dependency: Dependency `requests`: use_existing. Already covered by httpx.
  app/billing.py:3 unused_import: `os` is imported but never used.
  app/billing.py:8 unused_import: `requests` is imported but never used.
  app/billing.py:13 over_abstraction [review]: Abstract `InvoiceSink` has 1 implementation(s) ...
  app/billing.py:26 duplicate [review]: `retry_request` looks like a reimplementation of `with_backoff` (similarity 0.68)
  app/billing.py:36 stdlib_replaceable [review]: `chunk_invoices` hand-rolls what itertools.batched provides (Python 3.12+)
  app/billing.py:40 dead_code: Private function `_format_invoice` is never called anywhere in the repo.
...
gate: block
  kept: redundant_check on sync_invoices.invoices (app/billing.py:45), keep
...
findings: 7 confirmed, gate block
lines: app/billing.py 51 -> 26 after the fix (25 removed)
dependencies avoided: 1 (requests)

The card ends with per-tier Nemotron calls, latency and tokens when Token Factory is live. demo/layout.ps1 is an internal helper that opens the psmux layout used to record the demo video.

How it works

flowchart LR
    A[Coding agent] -- "check_reuse (before writing)" --> L
    A -- "verify_lean (before finishing)" --> L
    E[Per-edit hook<br/>PostToolUse] -- "findings after each edit" --> L
    H[Stop hook] -- blocks finish --> L
    subgraph L[LeanGate MCP server - local]
      I[Repo index<br/>tokens + AST shape]
      S[Static checks<br/>bloat, errors, security, imports]
      M[Mem0 memory]
    end
    L -- "fixed-answer decisions" --> J[Jev<br/>typed decisions]
    J -- "review / escalate" --> N[Nemotron Nano / Super<br/>Nebius Token Factory]
    L -- "minimize / ground / deps" --> R
    subgraph R[Verification service - Nebius]
      W[Nemotron rewrite] --> P[Jev pre-check] --> X[Sandbox: same tests,<br/>both versions]
      T[Tavily: official docs<br/>at pinned version]
      Q[PyPI + OSV.dev]
    end

Two checkpoints, not streaming. Half-written code always looks bloated (helpers not yet called, imports not yet used), so LeanGate judges complete units:

1. Before writing: at session start, the agent is told the repo's house helpers: the functions the repo routes outbound HTTP, subprocesses, YAML, unpickling and dates through (Sentry's safe_urlopen, Django's timezone.now), learned from the index by following calls and counting callers. A grep for the task's words never finds them. check_reuse("retry HTTP calls with backoff") → adapt: with_backoff (app/utils/retry.py:11) is there for a general-purpose helper the agent's own search didn't find.

2. Before finishing: verify_lean() reads the working tree vs HEAD and returns gate: block | pass with findings.

Between the two, the per-edit hook hands the agent each file's new static findings right after it writes the file. The Stop hook enforces checkpoint 2: the agent can't end its turn while blocking issues remain, and it runs on a fast path (static analysis + Jev, about 1.5 s) so it never slows the loop.

Who does what

Confidence routing (cheap first, big models only when needed)

Jev returns a typed choice with a confidence, which maps to an action:

Static analysis and Jev count as two independent pieces of evidence. When they agree, their confidences compound (static 0.92 + Jev 0.71 → 0.98) and the call is accepted with no model hop (jev+static). When they disagree (jev-disputed), Nemotron settles it. Jev is also asked a specific question for each kind of finding, with what "yes" and "no" mean, plus the module or the original function it needs to see. On the demo change this took Jev from 0.51–0.77 to 0.55–1.00 confidence and Nemotron decision calls from 7 to 0 (full verify 6.3 s → 3.1 s); Nemotron's job there becomes disputes, rewrites and test generation.

Why Nano reviews: replaying the demo's 8 uncertain decisions through every tier, Nano gave the same answer as Super on all 8, at about the same latency (~1 s on Token Factory) as the smallest tier. Ultra disagreed with both on a clear duplicate, so it isn't the default top judge; it still generates tests.

Paying for inference once

Model calls are cheap; asking the same question twice is the waste. Three rules keep the bill and the wait down:

• Decision cache. A model's answer is stored per repo, keyed by the question, the code it's about and the models in use. The Stop hook asks again every time the agent tries to finish, so a repeat run on unchanged code makes no model calls at all. Changed code, or a different model, is asked again. LEANGATE_DECISION_CACHE=0 turns it off.

• No model for what can't block. A finding under the block bar (an unused import, a style simplification) is reported on its static evidence alone. Nemotron's "what's missing" items are the exception: Jev always rules on those. LEANGATE_CONFIRM_MINOR=1 sends everything to Jev, as before.

• Nano proposes "what's missing", Super settles disputes. The review runs on Nano (LEANGATE_MISSING_TIER), every file's review runs at once, and only an item Jev disputes goes on to Super.

Measured on Zulip with every provider live: 11 agent-written modules (320 lines, from the benchmark), a full verify.

Most of the old full verify was the "what's missing" review running one file after another on Super (13 of 23 s). The live dashboard shows this breakdown for every run (below).

Learning each repo

LeanGate keeps a profile per repo (profile.json next to its index; nothing crosses between repos) and gets better and faster with every run in it:

• Reuse map. When new code does a job by calling a project helper, whether LeanGate suggested it or the agent found it, the job is remembered with that helper, under the new function's words and the words of the task the agent was given. It reaches the next agent three ways, none needing a model call: with its task (the prompt hook names the helpers earlier changes used for a task like it), in check_reuse (on Superset, a reworded "make a chart title safe as a file name" went from "write new" in 1.5 s with 5 Jev calls to "reuse sanitize_filename" in 0.27 s with none), and in verify_lean (new code redoing a job learned twice is flagged as a reimplementation). On the fresh-repo benchmark, agents given the hint reused the helper in 18 of 19 runs, against 14 of 19 for the same tasks with LeanGate's memory wiped, in 5 turns instead of 8 (RESULTS_fresh.md).

• Calibration. Each rule's outcomes here (confirmed, dismissed, fixed by the agent, rejected by a person) are counted. A rule the decider always confirms stops being asked about; a bloat or error-handling rule people keep rejecting becomes a hint. Security rules are never relaxed by learning.

• Precedents. Confirmed findings are retrieved by similarity and handed to the what's-missing review as "issues confirmed before in this repo" (retrieval over the repo's own history, no model training).

• The repo's endpoint habit. LeanGate reads the existing endpoints and learns how they check permissions (Superset: 328 of 337 use @protect / class_permission_name; edx-platform: 73% permission_classes). Where most do, a new endpoint without a check is flagged; where most are public, nothing is. On the benchmark's code it fired only where the blind reviewer also found missing authorization.

The dashboard's "What LeanGate has learned here" card shows all of it.

Every decision in a report carries its source (e.g. jev, jev>nemotron-super, static) and whether it came from the cache, so you can see which model made each call. Findings the decider chose to keep (a guard on a public function, say) come back in the report's kept list, with the decision that kept them.

What it detects

Three groups: code production doesn't need (bloat), code it can't survive (error handling, security), and code that won't even import (invented internal APIs). Fewer lines was never the goal. Validation, retries, error handling and logging that protect production are kept, and a dedicated "keep or remove" decision guards exactly that.

Beyond bloat, LeanGate flags code production can't survive:

Security checks use Ruff's port of Bandit's tests (same S/B numbering, ~30 ms per file versus ~500 ms to import Bandit). "What's missing" only reviews changed functions that take outside input (routes, CLI commands, parameters that reach SQL, a shell, or the filesystem), and only on a full verify, never in the Stop hook.

Grounding (Tavily)

Model knowledge is stale and version-blind. Before LeanGate suggests "use itertools.batched", it:

1. reads the repo's pinned Python and dependency versions (pyproject.toml, requirements*.txt, .python-version)

2. searches official domains only (docs.python.org, peps.python.org, PyPI, Read the Docs, GitHub) with the version in the query

3. has Jev judge the excerpts: supported | contradicted | unclear. A contradicted claim drops the finding.

4. returns citations with the finding, and caches by claim + version

Web text only reaches a judge that must answer with a fixed option key. It is never pasted into a rewrite prompt, which limits prompt-injection risk.

MCP tools

Setup

Requires Python 3.11+ and git. To use it: pip install "leangate[providers]", and keys in ~/.leangate/.env (a repo's own .env may supply provider keys too, but never endpoints: a cloned repo can't redirect your key and code to its server). To work on LeanGate itself:

git clone https://github.com/lambdabypi/leangate && cd leangate
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
pip install -e ".[all]"
cp .env.example .env    # add keys; any missing key falls back to an offline mode
python scripts/list_models.py   # needs NEBIUS_API_KEY: lists the Nemotron model IDs your key can use

Keys: NEBIUS_API_KEY (Token Factory), OPENROUTER_API_KEY (Jev via OpenRouter; TYPESAFE_API_KEY also works for TypeSafe directly), TAVILY_API_KEY, MEM0_API_KEY. With no keys at all, everything still runs: decisions use static-analysis confidences (so weak heuristics land in review, never auto), grounding uses curated doc links, and memory is a local JSON file. Set LEANGATE_MOCK=1 to force this.

Connect a coding agent

Claude Code:

claude mcp add leangate --scope user -- /absolute/path/to/.venv/bin/leangate-mcp   # Windows: ...\.venv\Scripts\leangate-mcp.exe
leangate --repo path/to/your/repo hooks          # shows what it would add; add --write to save it

Use the absolute path to leangate-mcp inside the venv you installed into: Claude Code starts the server itself, outside your activated shell, so a bare leangate-mcp only works if that venv happens to be on its PATH. The hooks command writes absolute paths for the same reason. The second command adds four hooks to that repo's .claude/settings.local.json (personal; it holds this machine's paths), keeping any settings already there:

So the agent hears about a duplicated helper or a missing timeout right after writing it, not after it has built three more files on top. Checks can't run mid-generation (no tool sees inside a model's output until an edit lands, and half-written code doesn't parse), so the per-edit hook is as early as code can be checked. The session hook covers the step before writing, without costing the agent a tool call.

Waiving a finding. The agent can reject a wrong bloat or error-handling finding with record_feedback. It can't waive a security finding: on the benchmark, Claude dismissed its own and the gate passed. It's told to stop and explain to the user instead, and its reason is kept. The user runs leangate waive (no arguments lists what agents asked for) or leangate waive <signature> --note "why", which suppresses it locally and writes .leangate/waivers.json. Commit that file and CI and teammates honor the waiver too. LeanGate reads the file from HEAD, so an agent editing it changes nothing until someone commits it, and the command refuses to run inside a Claude Code session. The hook entries are also in examples/claude-settings.json.

Codex: append examples/codex-config.toml to ~/.codex/config.toml.

Any MCP client: see examples/mcp.json.

Paste examples/AGENTS.md into your repo's AGENTS.md / CLAUDE.md so the agent knows when to call each tool.

In your editor (VS Code, or any LSP client)

leangate lsp is a language server. It checks the buffer as you type, with static checks only: no network, about 125 ms per debounced keystroke on the demo file. On save it confirms each finding with Jev (static + Jev, the Stop hook's fast path; set leangate.escalate to add Nemotron and Tavily). Severity follows the category: bloat is Information or Hint, error handling is a Warning, security is a Warning or an Error. Hover shows the reason, the decision trail (Static -> Jev agreed, or Nemotron Super -> Jev agreed for what's-missing findings) and citations. Quick fixes: remove an unused import, and replace a duplicate's body with a call to the existing function.

pip install -e ".[editor]"
cd editors/vscode && npm install && npx @vscode/vsce package --allow-missing-repository
code --install-extension leangate-0.1.0.vsix   # or Extensions > ... > Install from VSIX

The extension isn't on the Marketplace; build it locally as above. Settings, troubleshooting (LEANGATE_LSP_LOG=<file>) and other editors: editors/vscode/README.md.

Live dashboard

Every verify_lean and check_reuse run, whether from the MCP server, the Stop hook, the CLI or the editor, appends one event to ~/.leangate/<repo-hash>/events.jsonl. The file rotates at 2 MB and keeps one old copy. leangate dashboard serves a live view of those events on 127.0.0.1 only (port LEANGATE_DASHBOARD_PORT, default 8765): the latest report grouped into Security, Error handling and Bloat, each finding's decision trail and citations, what was kept on purpose, and how much was checked. Every location opens in VS Code (vscode://file/...). The agent's show_report tool, or LeanGate: Show Live Report in VS Code, starts the dashboard if needed and opens it. Nothing else opens a browser tab. The dashboard only reads files LeanGate already wrote. It calls no provider and isn't part of the Nebius service.

Time and cost per run. Every run records where its time went, from the moment LeanGate starts: building its clients, loading the index, finding the changes, static checks, the "what's missing" review, Mem0, confirming findings, and the gate. It also records each provider's calls, time and estimated cost, and how many answers came from the cache. The dashboard charts the repo's recent runs (bars split by phase, with LeanGate's cost as a line; click a bar to open that run), and each report opens with that run's breakdown.

Mission control. The Agents panel at the top shows one row per agent, for this repo or across all of them: Claude Code, Codex, Cursor and VS Code's agent are told apart by the name each sends when it connects to the MCP server, and hook, editor and CI runs are labelled too. For each one: runs, how many changes the gate blocked, issues caught right after an edit, unique issues by category, invented imports, how often LeanGate pointed it at existing code, and the estimated cost of LeanGate's own model calls. A team running several agents gets one standard and one view across all of them. Each agent's own usage is billed by its vendor and isn't shown.

Run the verification service on Nebius

docker build -t leangate-service .
docker run -p 8000:8000 --env-file .env leangate-service
# open http://127.0.0.1:8000/ for the web playground, /docs for the API

Step-by-step deploy as a Nebius Serverless Endpoint or on an AI Cloud VM: DEPLOY.md. Create the endpoint with --auth none so judges can open the playground; the engine routes stay protected by LEANGATE_SERVICE_TOKEN. Then point local MCP servers at it:

LEANGATE_REMOTE_URL=https://<your-endpoint> LEANGATE_SERVICE_TOKEN=<token>

The repo index, static analysis, and memory stay on the developer's machine. Only the snippets being rewritten or grounded are sent to the service.

Web playground

The service serves a single-page playground at / (plain HTML/CSS/JS, no build step) for people who don't want to install anything:

• Verify: paste files (or load the bundled "agent's bloated change"), get the gate, findings grouped by kind, the decision trail per finding (static → Jev → Nemotron), Tavily citations, and what was kept on purpose.

• Reuse search: describe what you're about to write; see existing candidates and a reuse / adapt / write_new call.

• Minimize: before/after diff and the sandbox equivalence result.

• A provider strip from /health shows which of Nemotron (Token Factory), Jev, Tavily, and Mem0 are live.

Behind it, POST /api/verify ({files, baseline?, pyproject?, escalate?}), POST /api/reuse and POST /api/minimize build a throwaway git repo per request (baseline committed, files on top) with its own LeanGate state, and delete both afterwards. Limits: 40 files, 200 KB per file, 1 MB per request, 30 requests/min per IP, and 6/min for /api/minimize, which runs code. /api/* is open by default; set LEANGATE_PLAYGROUND_TOKEN_REQUIRED=1 to put it behind the service token, or LEANGATE_PLAYGROUND_SANDBOX=0 to keep the playground from running submitted code at all. The engine routes answer 503 until LEANGATE_SERVICE_TOKEN is set.

Sandbox. Each test run is a pytest subprocess in a fresh temp dir with a wall-clock timeout, a capped output file, a stripped environment (no API keys), and a Python-level network block. On Linux it adds CPU, memory, file-size, open-file and process-count rlimits, kills the whole process group, tries an empty network namespace, and marks the server process non-dumpable so test code can't read its environment from /proc. On Windows only the timeout, output cap and Python-level block apply. This is defense in depth, not a security boundary on its own; see what the sandbox does and doesn't protect.

CI, GitHub Action, pre-commit

GitHub Action

Block PRs that add bloat, missing error handling or security problems. Runs offline, no keys needed. Uses the fast path (static analysis + Jev) by default.

# .github/workflows/leangate.yml
on: pull_request
jobs:
  leangate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # LeanGate diffs base...HEAD, so the merge-base must be present
      - uses: OWNER/leangate@v0.1.0
        with:
          fast: "true"              # "false" adds Nemotron + Tavily-grounded checks
          # block-severity: "0.7"   # default 0.6
          # fail-on-block: "false"  # report only
          # remote-url: ${{ vars.LEANGATE_REMOTE_URL }}
          # remote-token: ${{ secrets.LEANGATE_SERVICE_TOKEN }}

Findings show up as annotations on the changed lines and as a table in the job summary. The job fails when LeanGate blocks. Outputs: gate (pass/block), findings, report (path to the JSON report).

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/OWNER/leangate
    rev: v0.1.0
    hooks:
      - id: leangate-verify

This runs leangate verify --fast --staged on what you're about to commit: staged changes only, so untracked scratch files don't count. It skips commits that don't touch .py, pyproject.toml or requirements*.txt.

CLI in any CI

leangate verify --base origin/main --fast        # PR diff (base...HEAD); dependencies compared with the merge-base
leangate verify --staged --fast                  # what's staged
leangate --json verify --diff change.diff        # a diff file, JSON report

Exit codes: 0 pass, 1 blocked, 2 usage or environment error (not a git repo, no merge-base).

This repo's own CI (.github/workflows/ci.yml) runs the test suite on Ubuntu and Windows, Python 3.11 and 3.12, offline.

At production scale

Measured on a shallow clone of django/django (2,933 files, 527k lines, 9,167 candidate functions; Windows 11, Python 3.13):

The index is an exact inverted index (results identical to the old linear scan, checked on 60 query/setting combinations on django) with branch-and-bound pruning for the AST-shape score, persisted under the per-repo state dir and invalidated per file by mtime and size.

False positives on real code. With every line of httpx, rich and click (64k lines) marked as "added", duplicate findings fell from about 5.6 to 0.57 per 1,000 lines after tuning, and unused-import, unreachable-code and stdlib findings on those libraries went to zero (all were false positives). Recall: 19 of 20 planted agent-style rewrites of real helpers are caught, including ones that hard-code the original's parameters. The miss is a one-liner, which the stdlib check flags instead.

The same test for the error-handling, security and in-function checks (60k lines of httpx, rich and click, static only): all detectors together went from 3.06 to 1.41 findings per 1,000 lines after one round of tuning. Ruff's RET rules (else after return) were 100 of 123 redundancy findings and were dropped as style, and one-statement capability probes (try: return stream.isatty() / except Exception: return False) no longer block. The SQL, TLS, secret, eval, timeout and open-file checks found nothing in those mature libraries, and catch every planted case in the tests.

How we used NVIDIA Nemotron and Nebius

• Nemotron on Nebius Token Factory does every generative step, through Token Factory's OpenAI-compatible API (src/leangate/llm/nemotron.py):

  • Nano settles decisions Jev marks review (the common case, so the cheapest tier does it).

  • Super writes behavior-preserving rewrites in minimize, and settles decisions Jev marks escalate.

  • Nano is the "what's missing" reviewer: on a full verify it reads each changed function that takes outside input and names the access check, validation or error handling it lacks, which no static rule can see. Jev must confirm each item, and one Jev disputes goes to Super (src/leangate/analysis/missing.py).

  • Ultra generates pytest suites when the caller provides none.

  • Nano and Super as the coding agent in the benchmark: both wrote every module, with and without LeanGate, so the comparison runs entirely on Token Factory.

• Nebius AI Cloud / Serverless: the verification service (src/leangate/service/app.py, Dockerfile) runs untrusted code in the sandbox inside the Nebius-hosted container, not on the developer's machine.

Project status

Known limits:

• Python only.

• Duplicate detection is static. A copy that swaps an injected dependency for a concrete library (self.session.get vs requests.get) reads as a deliberate sibling and is missed; one-implementer ABCs that are public extension points in a library are still flagged.

• The sandbox is defense in depth (timeouts, rlimits, network block, stripped env), not a security boundary. Inside Docker the network block is likely Python-level only, and test code runs as the same user as the server, so a hostile submission can restart it. Real isolation needs a separate network-less sandbox container; until then, LEANGATE_PLAYGROUND_SANDBOX=0 keeps the public playground from running code. Run untrusted code in the Nebius-hosted service, not on a laptop.

• Rejections recorded with record_feedback live in ~/.leangate, so CI doesn't see them. Waivers made with leangate waive and committed in .leangate/waivers.json are shared.

• House helpers are found for a fixed set of call families (HTTP, subprocess, YAML, pickle, date parsing, the current time), through module-level functions only. When a repo also wraps the library in client classes (Sentry's API clients), the classes' own calls count as direct calls, which lowers the helper's adoption and keeps its finding a hint.

License

MIT