Vinv watches a real run of your Python services and hands your AI coding agent the actual execution evidence — traces, argument values, the failing frame — instead of leaving it to guess from static text. Then it won't let a fix land until it passes acceptance tests written before the fix that the agent never sees.

Your coding agent (Claude Code, Cursor, Copilot…) is the only LLM. No new bill, no provider keys.

Install

pip install vinv

Or run any engine with zero install via uv:

uvx --from vinv exerciser campaign ./my-service --budget 20

_{First run fetches a one-time ~100 MB local embedding model. Python 3.12–3.14.}

What you get — Run · Test · Find · Prove

• 🏃 Run — brings every service in your repo up under tracing with zero edits to your code: timings, arguments, return values, call trees, from the real run.
• 🧪 Test — drives real requests through every endpoint (valid, boundary, negative, authenticated) and banks each response as a permanent regression case.
• 🔎 Find — surfaces what actually broke or slowed down: server errors, crashes, latency hotspots, memory leaks, duplicate recomputation, and dead code — each tied to the exact source line. Plus semantic code search: ask by meaning, get ranked symbols with def bodies and line numbers.
• ✅ Prove — hands that evidence to your coding agent, then verifies its fix against acceptance tests it never sees. A "faster" change that alters any output is auto-reverted.

Dead code — zero setup

Not everything needs a run. index deadcode <repo> (or the vinv_deadcode MCP tool) statically finds every function, class, and method nothing references — no tracing, no index, no config — and reports each with its file and line. It even catches transitively-dead chains (code whose only callers are themselves dead), and can date each symbol from git to tell you whether it was never wired up or lost its callers. The one Vinv feature that pays off before you run a thing — delete with confidence.

Context beats model size

Vinv found four bugs and one performance problem in fastapi/full-stack-fastapi-template (~44k★). Same five issues, same prompts, Vinv grading every run:

_{One trial per condition — a demonstration, not a benchmark. The evidence is what moved, not the weights.}

On the same template the optimization loop detected connection-pool starvation from live traces alone, dispatched the fix, and proved it: sustained-load median 75.6ms → 41.2ms, 45.4% faster (95% CI [36.3%, 45.8%]), responses byte-identical. Upstream on Hugging Face, it found and proved an allocation fast-path in smolagents — ~37,000× less transient allocation, output byte-identical across 2,015 inputs (PR #2572).

The engines

pip install vinv installs one package that ships every engine as a console script:

Works with any MCP client

Vinv is also an MCP server — add it once, globally, and point Claude Code, Cursor, or any MCP-compatible agent at it. It finds your open workspace automatically via MCP roots, so a single config follows whatever repo you have open:

claude mcp add vinv -- npx -y vinv-mcp

Your agent gets the full tool set: vinv_query (semantic code search), vinv_deadcode (unreferenced code), vinv_index (build/refresh the index), rank_suspects (fault localization over real runs), runtime values_of / slice / coverage_of, and a vinv_session tool that drives the whole verify/optimize loop from chat. The index builds in the background on first use. See vinv-mcp.

Privacy

100% local. No telemetry, no analytics, no usage pings. Traces stay on your machine and sensitive values are redacted. Apache-2.0.