VinvAI

Vinv records a real run of your Python backend and checks your coding agent's "done" — replayed start, live port, acceptance tests the agent never sees.

vinv.ai · Feedback & issues · Python first · TS & Go next · first month free, then $10/mo

Your agent has never watched your code run — it edits the wrong handler, invents return shapes, then grades its own homework: "Done — all tests pass" while the server won't even start.

Vinv records the run, ties every request to the exact line that served it, hands that evidence to your agent — and when the agent claims a fix, Vinv checks it independently: replayed start, live port, acceptance tests the agent never sees. One click reverts everything an episode touched — untracked files included.

// the loop — explore the graph, ask with evidence, dispatch a fix, judge the verdict

_{Seven real screens from a live install, in order: the Code Graph · graph → source · Ask Vinv · an answer with runtime citations · diff impact of a change · Vinv asking for your verdict on a dispatched fix · the guided walkthrough that gets you there.}

// WHAT VINV DOES

• Watches your code run — a zero-edit Python tracer records your code's calls as they happen: timing, memory, arguments, returns, errors, and the request that triggered each one.
• Maps your codebase — a persistent semantic index + interactive Code Graph, updated incrementally on save, that survives every agent session.
• Answers with evidence — Ask Vinv cites the exact symbols behind every claim and marks runtime facts that went stale when the code changed.
• Closes the loop — hand an issue to your own coding agent; Vinv composes the evidence pack, dispatches it, and verifies the result itself.
• Works with the agent you already use — Claude Code, Codex CLI, Cursor (CLI & chat), Gemini CLI, Copilot Chat, Windsurf Cascade — over MCP and headless dispatch, in the editor or in a plain terminal.

// THE CONTEXT GRAPH

Four artefacts, one join. Vinv indexes the code (every symbol and call edge) and generates — from your own run — the traces (one span per call), the logs (timestamped call events from that same trace), and the metrics (per-symbol latency & memory), then ties all four to the exact function that handled each request. The artefacts are commodities; the join is not. One graph, served to your agent, instead of four tools it has to guess between.

// HOW IT WORKS

1. Trace — run your Python service under the bundled tracer: no SDK, no code changes, no dashboards. Calls are recorded with real values (summarized and redacted — see Data & privacy).
2. Index — every function and class is summarized, embedded, and ranked into a local semantic index with a call/inheritance graph; incremental updates on save keep it current.
3. Serve — two MCP servers hand the context graph to your agent: semantic code search, fault-localization rankings, observed values, call slices, coverage, blast radius.
4. Verify — after a dispatched fix, Vinv replays the recorded start command in a fresh process, requires the port to actually serve, and runs acceptance tests generated before the fix that the agent never sees. Failures feed the next attempt; inconclusive evidence escalates to your judgment card.
5. Learn — every decision and outcome is propensity-logged; retrieval and context-pack composition update only when off-policy evaluation shows a real win over your baseline (local, never uploaded).

// INSTALL

Install from vinv.ai — pick your editor (VS Code, Cursor, Windsurf, VSCodium, Trae).

[!NOTE] Marketplace publication of VinvAI.VinvAI is pending. Until it lands, use the VSIX from an authorized Vinv distribution: Extensions → ⋯ → Install from VSIX…, or:

code --install-extension vinv-<version>.vsix     # cursor/windsurf: replace `code` with your editor's CLI

Then open the Vinv panel in the Activity Bar and sign in (first month free, then $10/mo) — or run Vinv: Enter License Key. Vinv provisions its six engine binaries automatically after activation. Switching accounts? Vinv: Reset License clears the stored key.

// QUICKSTART — FIRST 10 MINUTES

1. Sign in — the walkthrough opens on first install; step 1 is activation.
2. Connect your AI — Vinv: Configure Project → provider + API key (OpenAI, Anthropic, Groq, or any OpenAI-compatible endpoint), or choose Use coding harness to route analysis through the agent CLI you already have. The search index itself is built from embeddings, which need an OpenAI-compatible key — Anthropic/Groq and harness mode cover analysis only.
3. Discover your project — Vinv: Discover Project builds the semantic index, writes a plain-language handbook to .vinv/vinv.md, and inventories your services.
4. Explore the Code Graph — Vinv: Open Graph Explorer. Your codebase as a map: search, layers, runtime overlay, diff impact.
5. Run a service under tracing — Set Up Service in the Services view, then Vinv: Start Service — or Vinv: Run Service (Cmd/Ctrl+Alt+R) for a traced debug run. Exercise it — every request is now evidence.
6. Ask Vinv — Vinv: Ask Vinv: ask anything about your code; answers cite their sources, runtime facts included.
7. Close the loop — Vinv: Fix with Harness (Closed-Loop Episode), or click Fix with Coding Agent on any graph node. Vinv dispatches your agent and verifies the result.

Lost at any point? Vinv: What Should I Do Next? names the single most valuable next action from your actual workspace state — and Help → Welcome → Get Started with Vinv re-opens the walkthrough.

Honest scope: Python backends first — other stacks get the index, graph, and QnA, but no runtime evidence (TS & Go next) · v0.0.x · works with six agents over MCP and headless dispatch (Gemini CLI: dispatch only — see Agent Setup) · Vinv does not do cost metering, security scanning of generated code, or production deployment.

// SOUND FAMILIAR?

// FEATURES

In the editor

Through your agent

In the background

// ONE INSTALL, ANY HARNESS

Vinv installs as an editor extension — but its capabilities are not trapped in the editor. The two MCP servers are plain stdio programs that your agent launches, reading the index and the captured runs straight off disk. Once Vinv has registered them, every MCP-speaking agent on your machine can use them — including from a bare terminal with no editor window open.

• Install once, wired everywhere. On startup (or via Vinv: Register Vinv MCP in Agent Tools) Vinv writes its launch spec into each agent tool it detects — ~/.claude.json (Claude Code, local scope), ~/.codex/config.toml, .cursor/mcp.json, VS Code's native MCP provider, ~/.codeium/windsurf/mcp_config.json. Idempotent, reversible, and no secrets in any of them: the servers read credentials from ~/.vinv/config.json and gate on your license themselves.
• The editor doesn't have to be running. Open a terminal in the same repo, run claude or codex, and vinv_query, rank_suspects, values_of, slice, coverage_of, callers_of, blast_radius, why_did_this_run and vinv_session all answer. The evidence lives in .vinv/, not in the extension host. (The servers run on the editor's own bundled Node, so the editor must stay installed — it just doesn't have to be open.)
• One memory, many agents. Index and traces are shared state on disk. Ask Claude Code in the terminal about a failure, switch to Cursor chat to write the fix, come back the next day to a fresh session — all three read the same graph and the same recorded run. Nothing to re-explain.
• Any other MCP client works too. Auto-registration covers the agents Vinv detects; anything else that speaks MCP can be pointed at the same two servers — copy the command / args block out of a registered config (it is just the editor binary running out/mcp/indexServer.js <workspaceRoot>).
• What still wants the editor: capture and dispatch. Building the index (Discover Project) and recording runs (Start Service) are editor-driven, and vinv_session action="fix" / action="run_sweep" queue durably to .vinv/requests/ — Vinv dispatches and verifies them the next time the editor is open. Reading evidence never needs it.

// AGENT SETUP

Vinv registers its MCP servers into every agent tool it detects (idempotent, reversible, no secrets in config files) — on startup, or via Vinv: Register Vinv MCP in Agent Tools. Episodes can dispatch to any of the seven targets across the six agents below (Cursor's block covers both its CLI and chat panel); the picker remembers your last choice, shows what's installed, and offers Install it for me for missing CLIs.

[!TIP] In any of these MCP-connected chats your agent already knows the workflow: the MCP servers instruct it to call vinv_query before grep and rank_suspects before reading source when debugging.

// MCP TOOLS REFERENCE

vinv-index — the codebase and the session:

vinv-runtime — the captured runs (read-only, provenance-stamped):

// SETTINGS

// DATA & PRIVACY

• Everything Vinv builds lives on your machine: per-repo state in .vinv/ (auto-gitignored), per-machine state in ~/.vinv/. Learning ledgers are local and never uploaded.
• Traces store bounded summaries, not raw values: strings become length + hash prefix; parameters with sensitive names (password, token, api_key, secret, authorization, credential) are flagged redacted and never have contents captured; everything is capped at 256 bytes by default.
• Product telemetry (PostHog, EU) follows your editor's own telemetry setting and carries event names, coarse counts, path-scrubbed error messages, and your account email (so your own installs group as one user) — no code, no prompts, no trace payloads. Engine logs leave your machine only inside the Vinv: Export Diagnostics (for Support) bundle you review yourself.
• License key lives in the OS keychain, plus an owner-only copy at ~/.vinv/license.json that the bundled engine binaries read to self-gate; MCP configs never contain secrets.

// TROUBLESHOOTING

// LINKS

• Website / install: vinv.ai
• Feedback & issues: github.com/VinvAI/feedback
• Contact: support@vinv.ai