AI Context

@vibgrate/cli

Local codebase intelligence for AI coding agents — graph, drift, and version-correct docs on your machine

Want to help? See CONTRIBUTING.md and good first issues.

npx @vibgrate/cli scan          # drift score + upgrade priorities

npm install -D @vibgrate/cli # install for repeat runs

vg answers three questions for any repo:

1. What is this codebase? — A deterministic code graph: call trees, import paths, impact surfaces, dependency facts.
2. How far behind is it? — A ranked [DriftScore](https://vibgrate.com/driftscore) (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritized fix list. Exposure is scored separately as a [RiskScore](https://vibgrate.com/riskscore); the two together are the [DriftRisk Index](https://vibgrate.com/driftrisk). The full methodology — formulas, sources, and limitations — is published as a whitepaper under CC BY 4.0 (DOI 10.5281/zenodo.21336304).
3. Can we fix it here? — VG Code, a coding agent whose search tool is the code graph, not a grep — in your terminal as vg code and as the VG Code panel in Vibgrate for VS Code — plus vg fix, ranked upgrade plans it can apply.

Everything runs on your machine. No API key, no network call, no data leaving your repo unless you explicitly push. The vibgrate command is an alias for vg — they are interchangeable.

---

See it run

A real vg scan replay — drift score, breakdown, and ranked priorities in one command. Animation plays right here on GitHub; nothing runs in your browser.

▶ Try the live, interactive CLI simulator →

Step through every command ( scan , build , ask , why , …) against real sample repos.

---

Try it in 10 seconds

No install, no signup:

npx @vibgrate/cli scan          # drift score + upgrade priorities

npx @vibgrate/cli build # build the code graph npx @vibgrate/cli ask "what does AuthService do?" npx @vibgrate/cli code # a coding agent — it asks before every edit

Install for repeat runs:

npm install -D @vibgrate/cli

npx vg scan # vg is the primary command; vibgrate is an alias

Local binaries live in node_modules/.bin — use npx vg (or an npm script) unless you install globally.

---

Windows installation

Windows is supported with Node.js 24 or newer. PowerShell is the preferred shell for the Windows installer:

irm https://vibgrate.com/install.ps1 | iex

If you prefer npm, install the CLI globally:

npm install -g @vibgrate/cli

For a one-off run without changing PATH, use:

npx @vibgrate/cli scan

A global npm install places the vg.cmd and vibgrate.cmd shims in npm's global prefix. Check the exact location with npm config get prefix; if vg is not found, add that directory to your user PATH, then open a new PowerShell window. Verify the installation with:

vg --help

vg doctor

vg doctor is a read-only diagnostic command. If vg conflicts with another command on your system, use the identical vibgrate command instead. Command examples elsewhere in this README use POSIX path syntax; adapt paths to PowerShell on Windows.

---

Use it with your AI assistant

vg serve starts [Vibgrate AI Context](https://vibgrate.com/library) — a local-first MCP server that gives any MCP-compatible assistant (Claude, Cursor, Windsurf, Copilot, Gemini CLI, …) your code map, offline drift, local models, and version-correct library docs, all from your machine (no account, nothing uploaded; thin local docs fall through to the hosted catalog unless you pass --local). No context-window stuffing, no hallucinated APIs. The map keeps itself fresh: when files change — including edits the assistant itself just made — the next tool call rebuilds it incrementally before answering, with no watcher or daemon involved.

node-turborepo/serve — vg serve --http starts Vibgrate AI Context. Live simulator .

Wire it up in one command:

vg install                      # interactive: pick your assistant(s) and done

vg install --all # install for every detected assistant at once

This writes the MCP config for your chosen tool(s) and installs a skill that teaches the assistant how to query the graph. After reloading your assistant you get graph-aware answers: call trees, impact analysis, drift findings, version-correct library docs — all from local data. The token savings are measured and published, methodology included, at vibgrate.com/cli/benchmarks/token-savings.

Browse all 21+ supported assistants and their skill descriptions at [vibgrate.com/skills](https://vibgrate.com/skills).

Cut what your assistant re-reads: context compression

Every turn, your AI assistant re-sends the whole conversation — including the 20,000-line test log, the 400-row JSON payload, and the grep output it has already acted on. You pay for that context again on every step. Vibgrate CLI compresses tool output and older turns before they reach the model, keeps the originals retrievable on your machine, and reports what it saved.

vg install claude --compress    # point Claude Code at the listener and start it (undo with `vg uninstall claude`)

vg savings # tokens and estimated dollars saved, today / 7 days / 30 days

There is no separate command to learn: compression is a mode of the server you already run and a flag on the installer you already use. vg install --compress writes the agent's own base-URL config, starts the listener in the background (or reuses one already running) and, for Claude Code, adds a SessionStart hook that brings it back after a reboot. vg serve --compress serves the code map and compresses in one foreground process; vg serve --compress --background starts only the listener and returns. For a single session without writing any config, vg serve --compress claude runs one agent through it and restores your environment when it exits. Inside vg code it is already on — bulky tool results are compressed before they re-enter the loop, and the model can pull any original back with vg_retrieve.

What it does, in the order it runs:

• Routes each block by what it is — JSON arrays, logs and build output, grep results, diffs, HTML, tables, config files, source code, prose — and applies the compressor built for that shape. Errors, ids, stack traces and the lines that match what you asked are always kept.
• Lossless first. Repeated lines, grep headings and diff index lines fold into byte-reversible markers. Lossy compression runs only when it saves clearly more, and never on file reads or edits, so read-then-edit stays exact.
• Nothing is lost. Compressed blocks carry a marker; the model (or you, with vg serve retrieve ) can pull back the original or just the slice it needs. Originals live in a short-lived local store — nothing is uploaded.
• Prefix-cache aware. The default cache mode compresses only the newest turn so your provider's prompt cache keeps hitting; token mode compresses everything eligible for the largest saving.
• Works with any agent. vg install --compress supports Claude Code, Codex, Cursor, Aider, Copilot, OpenCode, Cline, Continue, Goose, OpenHands, Gemini CLI, Kimi, Grok and more; vg uninstall restores their config byte-for-byte. Or use the SDK wrappers for the Anthropic, OpenAI and Vercel AI SDK shapes.

Everything runs locally and offline. The listener binds to loopback, forwards your provider credentials untouched, redacts secret shapes before anything is written to disk, and never phones home. vg serve config lists every knob and vg serve config set KEY VALUE changes one.

Tools

vg serve exposes 24 MCP tools (plus two memory tools with --memory):

• orient — start here: project overview, entry points, where to look first.
• search_symbols — find a symbol by name or literal string.
• query_graph — find code by meaning: symptoms, relationships, what-breaks-if.
• get_node — inspect one symbol: signature, callers, callees, area.
• find_path — shortest connection between two symbols, with each hop's edge kind; calls_only follows calls and gives each call-site line.
• impact_of — blast radius of a change: dependents, files, covering tests, risk.
• tests_for — which tests cover a symbol.
• get_graph_summary — code map overview: counts, languages, top areas and hubs.
• list_areas — code areas (communities) by size.
• list_hubs — most-depended-on symbols.
• get_facts — deterministic facts for a node (contract / invariant / characterization).
• guide_node — cited standards and practices for a node (OWASP/CWE).
• check_drift — offline dependency inventory with optional git who-added attribution.
• vuln_attribution — who introduced each open vulnerability, exposure windows, CRA remediation metrics.
• list_vulnerabilities — known vulnerabilities from the last vg scan --vulns: CVE, severity, CVSS, fixed version, and EPSS or known-exploited fields when that scan recorded them.
• upgrade_impact — what breaks if you upgrade a package: major distance, import blast radius, vulns fixed.
• list_models — local models on disk (Ollama / LM Studio / gguf).
• resolve_library — resolve a library to its canonical id and the version your project uses.
• library_docs — version-correct usage docs for a library, sliced to a token