`pip install vinv`

Vinv runs, tests, and finds issues in your services — with zero code changes.

_{Python services & APIs · runs on your machine · no account, no API keys, no telemetry}

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:

Setup	Fixed
Cheap commodity model + Vinv evidence	4 bugs + 1 optimization
Frontier model, working blind	1 bug
Cheap commodity model, working blind	nothing

_{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:

Engine	Command	What it does
exerciser	`exerciser campaign <repo> --budget N`	Start here. Coverage-guided API exerciser + oracle swarm — generates valid/boundary/negative/authenticated/fault/concurrent requests, banks a permanent regression suite, and reports which technique paid.
tracelens	`tracelens run -- <cmd>`	Zero-edit runtime tracer — captures timings, arguments, return values, and call trees from a real run.
index	`index query <repo>` · `index deadcode <repo>`	Rust semantic code index — search code by meaning, plus a source-only dead-code report.
identification	`identification consolidate <repo>`	Joins traces to source — builds the API surface + call-graph map, tying runtime evidence to the exact function.
bringup	`bringup list/start <repo>`	Brings services up under tracing — enumerates every service, then starts one instrumented.
handbook	`handbook generate <repo>`	Renders the codebase-discovery task your coding agent runs to map the repo (services, entry points). Prompt-only — no LLM calls of its own.
goal	`goal create <context>`	Distills a working context into one standing goal for fix/optimize episodes. Prompt-only.
embedder	`vinv-embedder serve`	Local embedding sidecar (granite-embedding-small) powering semantic search — runs on your machine, no cloud keys.
contracts	(library)	`lens_contracts` — the shared data contract every engine reads and writes.

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.

_{vinv.ai · github.com/VinvAI/VinvAI · Python first — TypeScript & Go next}

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vinv-0.0.6-py3-none-win_amd64.whl (3.3 MB view details)

Uploaded Sep 6, 2026 Python 3Windows x86-64

vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.5 MB view details)

Uploaded Sep 6, 2026 Python 3manylinux: glibc 2.17+ x86-64

vinv-0.0.6-py3-none-macosx_11_0_arm64.whl (3.2 MB view details)

Uploaded Sep 6, 2026 Python 3macOS 11.0+ ARM64

File details

Details for the file vinv-0.0.6-py3-none-win_amd64.whl.

File metadata

Download URL: vinv-0.0.6-py3-none-win_amd64.whl
Upload date: Sep 6, 2026
Size: 3.3 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vinv-0.0.6-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`bca49c77ba9cf237e80f457c41a89fe242a6b98c1cd019b33558a1e41eab193b`
MD5	`25c9fcab0b5cfcd718bc8833fbb1b3bb`
BLAKE2b-256	`7d1c17bee21934d94a6f1b9e7aa902d87d5e140c84d3cc79558a1873e87ec986`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vinv-0.0.6-py3-none-win_amd64.whl:

Publisher: publish.yml on VinvAI/VinvAI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vinv-0.0.6-py3-none-win_amd64.whl
- Subject digest: bca49c77ba9cf237e80f457c41a89fe242a6b98c1cd019b33558a1e41eab193b
- Sigstore transparency entry: 2741960710
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: VinvAI/VinvAI@a295cc0e530c692897c1cb3004220575a4393dd7
- Branch / Tag: refs/tags/pypi-v0.0.6
- Owner: https://github.com/VinvAI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@a295cc0e530c692897c1cb3004220575a4393dd7
- Trigger Event: push

File details

Details for the file vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Sep 6, 2026
Size: 3.5 MB
Tags: Python 3, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`b522ff01646d1caf877c5804dc1b8aea46b2757cbebc4b4a33b453fedb5937e2`
MD5	`76cba2313b775df2d30eef392be2afec`
BLAKE2b-256	`a5f86dd047a3fc24e83786bd95006df4920bf1fd8dc5f60523f88dfd11d89e76`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on VinvAI/VinvAI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vinv-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: b522ff01646d1caf877c5804dc1b8aea46b2757cbebc4b4a33b453fedb5937e2
- Sigstore transparency entry: 2741960743
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: VinvAI/VinvAI@a295cc0e530c692897c1cb3004220575a4393dd7
- Branch / Tag: refs/tags/pypi-v0.0.6
- Owner: https://github.com/VinvAI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@a295cc0e530c692897c1cb3004220575a4393dd7
- Trigger Event: push

File details

Details for the file vinv-0.0.6-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: vinv-0.0.6-py3-none-macosx_11_0_arm64.whl
Upload date: Sep 6, 2026
Size: 3.2 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vinv-0.0.6-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`a6a92baf1f050eeb86c102870e96d7b15cea8a62552e915e8c2c92b62e7a2238`
MD5	`9e1bc5173be6f1b948772626577ae1c7`
BLAKE2b-256	`eb18ac1f0d525b4e4bd8b129772249309b18bdddc3875deff1ebf2f394ca1dad`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vinv-0.0.6-py3-none-macosx_11_0_arm64.whl:

Publisher: publish.yml on VinvAI/VinvAI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vinv-0.0.6-py3-none-macosx_11_0_arm64.whl
- Subject digest: a6a92baf1f050eeb86c102870e96d7b15cea8a62552e915e8c2c92b62e7a2238
- Sigstore transparency entry: 2741960782
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: VinvAI/VinvAI@a295cc0e530c692897c1cb3004220575a4393dd7
- Branch / Tag: refs/tags/pypi-v0.0.6
- Owner: https://github.com/VinvAI
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@a295cc0e530c692897c1cb3004220575a4393dd7
- Trigger Event: push