Vinv

VinvAI

Tools for AI agents to test, fix and optimise your codebase.

Vinv connects runtime traces to the exact source that produced them, hands that evidence to the coding agent you already use, then re-runs the code to prove the fix actually works. It's not another coding agent — it's the evidence layer under the one you already use: your agent proposes, Vinv verifies.

Editor extension one click — install in

MCP server 16 tools — add to

See it in action · What it does · Under the hood · 2-min demo

One workspace context, built once — every agent reads the same .vinv/ store.

Why Vinv

84% of developers now use or plan to use AI coding tools — but more of them distrust the output (46%) than trust it (33%), and distrust nearly doubled in a year (Stack Overflow 2025, 49k developers).

The reason is familiar: the agent edits the wrong handler, invents return shapes, then grades its own homework while the server won't even start. Or it loops — test fails, agent edits the same function, test fails again — burning your context window on "let me verify."

Both failures share one root cause: the agent has never watched your code run. It argues from static text.

The industry automated *writing* code and left *proving* it entirely manual. Vinv automates the proving — and only then the finding and the fixing.

Install

Vinv works three ways — an editor extension, a CLI, or an MCP server for any agent. All three share the same local engines.

Editor extension

One click — install from vinv.ai, which opens the extension directly in your editor (VS Code, Cursor, Windsurf, VSCodium, Trae and Insiders). The listing lives on Open VSX and the VS Code Marketplace.

Or from your editor's CLI:

First run builds the engines — about 3 minutes, mostly compiling the Rust index; it also fetches a one-time ~100 MB local embedding model (uv and Rust required). First trace lands about a minute after that; everything after is seconds.

CLI (Python engines)

pip install vinv          # every engine as a console script

or run one with zero install:

uvx --from vinv exerciser campaign --budget 20

MCP server (any agent)

Give Claude Code, Cursor, or any MCP client Vinv's tools — one global config that finds your open workspace automatically via MCP roots.

Claude Code, Codex, Gemini CLI — installed once for every folder you open, not just the current one:

claude mcp add --scope user vinv -- npx -y vinv-mcp

codex mcp add vinv -- npx -y vinv-mcp

gemini mcp add --scope user vinv npx -- -y vinv-mcp

Claude Code defaults to the current directory and Gemini CLI to the current project, so both take --scope user ; Codex always writes to ~/.codex/config.toml and has no scope flag.

Other clients: add { "command": "npx", "args": ["-y", "vinv-mcp"] } under mcpServers.vinv . See vinv-mcp — 16 tools: semantic search, dead code, fault localization, runtime values/slices/coverage, and the verify/optimize loop.

Build from source — for contributors

git clone https://github.com/VinvAI/VinvAI ~/.vinv/engines && cd ~/.vinv/engines && ./install.sh

Windows (PowerShell):

git clone https://github.com/VinvAI/VinvAI $HOME\.vinv\engines; cd $HOME\.vinv\engines; .\install.ps1

The loop, in one picture

Run → Test → Find → Prove. Point Vinv at a Python repo; it does the rest — no code changes, no API keys.

flowchart LR

T[Trace] --> I[Index] --> S[Serve MCP] --> V[Verify] --> L[Learn] --> T

• Run — brings every service up under tracing with zero edits, capturing timings, arguments, return values and call trees from the real run.
• Test — drives real requests through every endpoint (valid, boundary, negative, authenticated) and banks each response as a regression case.
• Find — surfaces what actually broke or slowed down — server errors, crashes, latency hotspots, dead code — each tied to the exact source line.
• Prove — hands the evidence to the agent you already use, then verifies its fix against acceptance tests written *before* the fix that it never sees. A "faster" change that alters any output is auto-reverted.

Your agent is the only LLM — no new bill, no model picker, no provider keys. See the full walkthrough on vinv.ai/#under-the-hood .

See it in action

Not a lab benchmark — real findings, filed on real projects (scikit-learn, watermarks-remover, semantica, FastAPI, Typer, smolagents), every one with an upstream thread you can open. 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. The full set with screenshots: vinv.ai/#catches.

Dead code — proven by what never ran

Static tools only prove *"nothing references this."* Vinv proves *"no capture ever executed this,"* carries each untraced island with the live callers that still point at it, and lets your agent return the verdict — integrate, delete, or keep.

semantica#1176 is the discipline in one thread: a maintainer flagged two symbols as importable downstream, Vinv restored them with deprecation warnings, and the same maintainer merged.

Optimization — a speedup that has to prove itself

Every call is timed and charged to the symbol that spent it. A candidate fix ships only if a paired-bootstrap 95% CI clears zero *and* the behavior suite replays byte-identical — faster-but-different is auto-reverted.

Bug report — bugs that only exist while something runs

Scanners read source and guess. Vinv drives the service and watches what comes back:

• drive — every discovered endpoint, exercised with inputs nobody wrote.
• judge — a 500 is not a finding on its own; the oracle names the status that *should* have come back.
• hand over — ships as an evidence pack: repro command, caller chain, real argument values.

On fastapi/full-stack-fastapi-template (~44k★), the authenticated sweep filed discussion #2454 — four endpoints answering 500 to input that should be 4xx, one repro each — then another contributor reproduced all four against master, file-and-line: *"checked against master — they're all real."*

What Vinv gives your agent

One loop, grouped by what you came to fix. Each capability links to a live