VinvAI

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://images.vinv.ai/vinv-banner-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="https://images.vinv.ai/vinv-banner-light.png">
  <img src="https://images.vinv.ai/vinv-banner-light.png" alt="Vinv — runs, tests, and finds issues in your services with zero code changes, then helps your AI agent fix what breaks and proves it." width="880">
</picture>

<br><br>

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

It watches a real run of your Python services and hands your 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 that fix passes acceptance tests written *before* it, that the agent never sees. All local, through the agent you already pay for.

<sub>Python first — services and APIs. TS & Go next.<br>No account. No API keys. No telemetry. Everything runs on your machine.</sub>

<br><br>

<a href="https://www.youtube.com/watch?v=EkUjPWKHAvI"><img src="docs/media/vinv-demo-poster.jpg" alt="Watch the 2-minute Vinv demo — run, test, and find issues in your services with zero code changes" width="820"></a>

<sub><a href="https://www.youtube.com/watch?v=EkUjPWKHAvI"><b>▶ Watch the 2-minute demo</b></a> — from a cold repo to a proven fix</sub>

<br><br>

<img src="https://images.vinv.ai/vinv-loop.png" alt="From cold repo to production-ready: Vinv's nine stages around your coding agent — bring up, trace, index, map, exercise, find, dispatch, verify, learn — each annotated with what it does and which engine runs it" width="900">

<sub>One command starts it. Vinv drives the other eight stages — every arrow is evidence, not a guess.</sub>

<br><br>

[![License](https://img.shields.io/badge/license-Apache--2.0-D71921?style=flat-square)](LICENSE)
[![Version](https://img.shields.io/open-vsx/v/VinvAI/VinvAI?style=flat-square&color=D71921&label=version)](https://open-vsx.org/extension/VinvAI/VinvAI)
[![Downloads](https://img.shields.io/open-vsx/dt/VinvAI/VinvAI?style=flat-square&color=D71921&label=downloads)](https://open-vsx.org/extension/VinvAI/VinvAI)
[![Tests](https://img.shields.io/github/actions/workflow/status/VinvAI/VinvAI/test.yml?branch=main&style=flat-square&label=tests&color=19D721)](https://github.com/VinvAI/VinvAI/actions/workflows/test.yml)
[![Lint](https://img.shields.io/github/actions/workflow/status/VinvAI/VinvAI/lint.yml?branch=main&style=flat-square&label=lint&color=19D721)](https://github.com/VinvAI/VinvAI/actions/workflows/lint.yml)
[![Open issues](https://img.shields.io/github/issues/VinvAI/VinvAI?style=flat-square&color=D71921&label=open%20issues)](https://github.com/VinvAI/VinvAI/issues)
[![100% local](https://img.shields.io/badge/100%25%20local-no%20telemetry-D71921?style=flat-square)](#privacy)

**Install:** [**Open VSX**](https://open-vsx.org/extension/VinvAI/VinvAI) · [**one-click, pick your editor**](https://vinv.ai/#install)

**[01 FIND](#01-find--what-actually-ran) · [02 FIX](#02-fix--through-the-agent-you-already-pay-for) · [03 PROVE](#03-prove--or-revert-it) · [04 LEARN](#04-learn--from-what-survived)**

</div>

## What you get, in one loop

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

- **🏃 Run** — brings every service in your repo 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 and dead code — each tied to the exact source line.
- **✅ Prove** — hands that evidence to the agent you already use (Claude Code, Cursor, Copilot…), 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.

<sub>Your agent is the only LLM — no new bill, no model picker, no provider keys. Everything runs on your machine.</sub>

## The problem

84% of developers now use or plan to use AI coding tools. More of them **actively distrust** the output (46%) than trust it (33%) — and distrust nearly doubled in a year ([Stack Overflow 2025, 49k developers](https://survey.stackoverflow.co/2025/ai/)). You know why: the agent edits the wrong handler, invents return shapes, then grades its own homework while the server won't even start.

Or it gets stuck — test fails, agent edits the same function, test fails the same way, agent edits it again, burning your context window on "let me verify." Anthropic's own research documents agents "stuck in loops, repeating the same failed approach" when they lack codebase context.

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

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

## Context beats model size

Receipts first — then how the loop produces them.

Vinv found **four bugs and one performance problem** in [fastapi/full-stack-fastapi-template](https://github.com/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**. Blind, the commodity model scored zero. Hand it the failing frame, the caller chain, and the real argument values, and it beats a stronger model guessing from static code. **The evidence is what moved, not the weights.**

On that same pristine template the optimization loop later detected — from live traces alone — that the app's default database pool makes requests **queue for connection checkouts** under concurrent load, dispatched the pool-sizing fix, and proved it: sustained-load median **75.6ms → 41.2ms, 45.4% faster (95% CI [36.3%, 45.8%])**, responses byte-identical. Two earlier attempts whose measurement windows couldn't certify the win were **auto-reverted** — the accept landed only when the evidence did.

<div align="center">
<img src="https://images.vinv.ai/vinv-pool-optimization-proof-light.gif" alt="Vinv on the FastAPI template: detects connection-pool starvation, proves 45.4% sustained-load median improvement with a paired-bootstrap 95% CI, auto-reverts uncertified attempts" width="720">
</div>

### Same discipline, upstream on Hugging Face

Pointed at [huggingface/smolagents](https://github.com/huggingface/smolagents) (~28.5k★) — a public Apache-2.0 agent framework, no affiliation — the allocation loop found and proved a fast-path in `sanitize_for_rich`. Benchmarked with `tracemalloc` on a realistic 4&nbsp;KB log line: transient per-call allocation **36.27&nbsp;KB → 0.00&nbsp;KB (~37,137× less)**; end-to-end on `log_task`, **~615.7&nbsp;KB → ~125&nbsp;B** across 3 calls; output byte-identical across **2,015** inputs. Upstream as [**PR #2572**](https://github.com/huggingface/smolagents/pull/2572).

<div align="center">
<a href="https://github.com/huggingface/smolagents/pull/2572"><img src="docs/media/smolagents-pr-2572.png" alt="PR #2572 on huggingface/smolagents — benchmarked perf fast-path for sanitize_for_rich" width="720"></a>
<br>
<img src="docs/media/smolagents-pr-2572-diff.png" alt="Light-theme GitHub Files changed view for smolagents PR #2572 — the fast-path in src/smolagents/utils.py" width="720">
<br><sub><a href="https://github.com/huggingface/smolagents/pull/2572">huggingface/smolagents#2572</a> · benchmarked allocation improvement · reproducible proof in the PR</sub>
</div>

That is *how come after it*: oracles find the waste, your agent proposes the edit, paired-bootstrap + byte-identical replay decide accept or revert, and only then does anything go upstream. The rest of this README is the machinery behind those receipts.

## Install

**Use it from your IDE, your CLI, or any MCP-compatible agent.** Vinv isn't another coding agent — it's the runtime-evidence layer *underneath* the one you already use, exposed as MCP servers (`vinv-index`, `vinv-runtime`, `vinv-exercise`) that Claude Code, Cursor, Codex, Copilot and Windsurf pick up automatically.

One click from the marketplace — [**Open VSX**](https://open-vsx.org/extension/VinvAI/VinvAI) — or straight from your editor's CLI:

| Editor | Command |
|---|---|
| VS Code | `code --install-extension VinvAI.VinvAI` |
| Cursor | `cursor --install-extension VinvAI.VinvAI` |
| Windsurf | `windsurf --install-extension VinvAI.VinvAI` |
| VSCodium | `codium --install-extension VinvAI.VinvAI` |
| Trae | `trae --install-extension VinvAI.VinvAI` |
| VS Code Insiders | `code-insiders --install-extension VinvAI.VinvAI` |

<sub>First run builds the engines — about 4 minutes: it compiles the Rust index and fetches a one-time ~500 MB local embedding model ([uv](https://docs.astral.sh/uv/) and [Rust](https://rustup.rs) required). First trace lands about a minute after that; everything after is seconds.</sub>

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

<sub>Windows (PowerShell):</sub>

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

## Under the hood: the oracle roster

The **Test** stage above isn't one tester — it's a set of oracles, each hunting a different class of defect, all writing into the same findings and the same fix-dispatch path. You never need to think about them to use Vinv; open this if you want the full list and how the budget is spent.

<details><summary><b>The full oracle ros