Tools and Algorithms for AI agents to test, fix and optimise your codebase.
Install once. Every agent on the repo reads the same runtime context.
install
One install. Every agent gets the same context. Vinv is not another coding agent — it is the evidence layer under the one you already use.
Deep link not firing? Open VSX has the listing.
install the package
pip install vinvregister it with your agent — pick one
claude mcp add --scope user vinv -- npx -y vinv-mcpcodex mcp add vinv -- npx -y vinv-mcpgemini mcp add --scope user vinv npx -- -y vinv-mcp
No editor needed. Claude Code, Codex, Gemini CLI — every Vinv tool, in whatever harness you drive.
demo
see it in action
Filed on scikit-learn, FastAPI, Typer, watermarks-remover, graphify. Every screenshot links to the thread. All of it driven by Cursor running Composer 2.5 with Vinv installed — not a frontier model. The evidence did the work, not the model.
Dead code proven by what never ran.
Static tools only prove nothing references it — blind to dynamic dispatch, flags and registries. So the candidates pile up.
- 01observeNo capture ever ran it. With no traces on disk, nothing is called dead.
- 02connectThe unit is a section: an island of untraced symbols, carried with its live callers.
- 03adjudicateFive to a prompt, so your agent can say “this is the older copy of that one”.
Waste you can measure — and a fix that has to prove itself.
Every call timed and charged to the symbol that spent it — then the fix has to certify itself against the same trace before it lands.
- 01traceTiming, memory, arguments and returns per call. No SDK.
- 02locateRanked by the time you would actually get back, not raw self-time.
- 03provePaired-bootstrap 95% CI plus a byte-identical replay. Faster-but-different is reverted.
and when nobody upstream is grading
From live traces alone: the default database pool queues requests for connection checkouts under load. Median 75.6ms → 41.2ms, 45.4% faster (95% CI [36.3%, 45.8%]), byte-identical. Two earlier attempts that could not certify the win were auto-reverted.
Bugs that only exist while something is running.
Scanners read source and guess. Vinv drives the service and watches what comes back.
- 01driveEvery discovered endpoint, exercised with inputs nobody wrote.
- 02judgeA 500 is not a finding. The oracle names the status that should have come back.
- 03hand overShips as an evidence pack: repro command, caller chain, real argument values.
context beats model size
Finding them is half of it. Same issues, same prompts — only what the model is handed changes:
| Commodity model + Vinv evidence | 4 bugs + 1 optimization | |
| Frontier model, blind | 1 bug | |
| Commodity model, blind | nothing |
One trial per condition — a demonstration, not a benchmark. Give a commodity model the failing frame and it beats a stronger model guessing. The evidence moved, not the weights.
the part nobody automated
84% of developers use AI coding tools, and more actively distrust the output (46%) than trust it (33%). The agent edits the wrong handler, then grades its own homework.
We automated writing and left proving manual. The work moved instead of disappearing. Vinv automates the proving.
dead code, from what actually ran
Vinv can say: no capture ever executed this, here is what still references it, and here is the traced neighbourhood it would wire back into.
Reachability is the whole question: “referenced but never taken” and “nothing points at it” lead to opposite decisions. Your agent returns the verdict — integrate, delete, keep — with what breaks if it goes.
Two refusals: nothing is dead without a trace on disk, and nothing is dropped silently — so “12 sections” never hides “300 were dropped.”
what it does
Semantic code search
Ask by meaning, get ranked symbols with line numbers. The model runs on your machine.
Code Graph
Every symbol and call edge, updated as you save, with the runtime on top.
Runtime tracing
Timing, memory, arguments and returns per call, joined to the line that produced them. No SDK.
Rank suspects
Symbols ranked by fault-localization score over real passing and failing requests.
Dead code
Connected sections nothing ever executed, split by reachability, with the live callers that still point at them.
Recoverable time
Hotspots ranked by the time you would actually get back — predicted, then proven.
Verified fixes
Replayed start, live port, tests the agent never sees. One click reverts the lot.
under the hood
Eight ways of breaking your code, all writing into one findings list:
| HTTP exerciser | Every discovered endpoint, driven — schema-valid, boundary, negative, multi-step auth |
| Differential oracle | A handler against a reference implementation — for a parser, CPython itself. Disagreement is the bug report |
| Fault injection | Adversarial-but-legal shapes at every dependency boundary |
| Concurrency oracle | Deterministic interleavings — state that corrupts in parallel, lock orders that deadlock |
| Environment oracle | Upstream symbols whose signature moved under you |
| Golden I/O baselines | A “faster” change that quietly dropped a field |
| Dead code | Untraced islands, with the live callers that still point at them |
| Runtime analysis | Hotspots, leak suspects, duplicate recomputation, throughput ceiling |
One budget, allocated by Thompson sampling over (target × technique × oracle). . Cost is measured, not assumed. Credit is paid once per defect signature. Which technique pays on your repo is learned across runs.
Anything unverifiable runs sandboxed — disposable repo copy, no network, no subprocess. Which tier you got is probed, not assumed.
01 — find what actually ran
Static scanners guess. Vinv records a real run and ranks what failed, what never executed, what was slow. Every finding names a symbol, a line and the trace. Nothing serving? Five oracles need no port.
02 — fix through the agent you already pay for
Evidence packs go to your own agent — Claude Code, Codex, Cursor, Gemini CLI, Copilot Chat, Windsurf Cascade. Your agent is Vinv's only LLM. No new bill, no keys. Each pack comes from one context graph — code, traces and metrics joined on the function that handled the request. The artefacts are commodities; the join is not.
03 — prove it or revert it
Replayed start. Live port. Acceptance tests authored before the fix, stored outside the workspace, required to fail twice on the broken code — a test that passes pre-fix is thrown away.
Around that: a static pre-gate, an anti-cheat audit over the diff and untracked files (test edits, swallowed exceptions, shadow modules), and a judge that can push toward scrutiny but can never rescue a failed gate. One click reverts everything an episode touched.
04 — learn from what survived
Two local ledgers, neither uploaded. What Vinv retrieves is chosen by Thompson sampling, and the exact propensity is logged with every decision — what an unbiased off-policy estimate needs later. Attribution is an exact Shapley value, so “did runtime evidence help” is computed, not claimed.
A configuration is promoted only when every gate holds, then serves at 5% and rolls back after three negative rewards. On this repo's own ledger — 800 decisions, 770 joined — it promoted top-k 10 (+0.173, 95% CI [+0.081, +0.317]) and blocked both other candidates. It admitted exactly the measured winner. Full math, file and line, is in the repository.
Every decision has a published method behind it:
| Which oracle gets the next unit of budget | Thompson sampling over (target × technique × oracle), credit paid once per defect signature |
| Which inputs to try next | Thompson sampling over Beta posteriors, decayed by half each run so stale lessons expire |
| Which live code a dead section belongs to | Personalized PageRank keeping only traced neighbours |
| Accept or revert a speedup | Paired bootstrap 95% CI plus byte-identical replay |
| Why throughput stops scaling | Universal Scalability Law over a bounded concurrency sweep |
| Behavioural invariants | Daikon-style dynamic invariants with Laplace confidence |
| Memory-leak suspects | Theil–Sen slope over per-session retention |
| Breaking a stuck agent | Nash bargaining — continue only if exploring beats asking you |
| Did the context pack help | Exact Shapley attribution — computed, not asserted |
| Promoting a retrieval config | Off-policy evaluation gates, then a 5% canary with automatic rollback |
The learning math, file and line behind every claim, is in the repository.
A zero-edit tracer ties every runtime span back to the source symbol that produced it. Code, traces and metrics, joined on the function that handled the request. That one graph is what your agent queries over MCP. The embedding model runs on your machine.
why the verdict holds
A change that alters any observable output is reverted — even when it is faster. When an agent starts repeating itself, Vinv ends the loop and hands you a verdict instead of a token bonfire. And when a “verified” fix is still wrong, you dispute it and the loop reopens.
Your agent says it's done. Vinv says prove it.
The full story, the methods, and the code are in the repository README.