ai-context

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 (0–100) with runtime/framework lag, dependency age and EOL proximity, and a prioritized fix list. Exposure is scored separately as a RiskScore; the two together are the DriftRisk Index. 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

---

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.

---

Use it with your AI assistant

vg serve starts Vibgrate AI Context — 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.

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.

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 <agent> --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 <hash>) 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 <agent> --compress supports Claude Code, Codex, Cursor, Aider, Copilot, OpenCode, Cline, Continue, Goose, OpenHands, Gemini CLI, Kimi, Grok and more; vg uninstall <agent> 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.
• 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 budget.
• compress_content / retrieve_original / compression_stats (with --compress) — shrink a tool output before it enters the context, expand a marker back to the original or just the slice you need, and report what compression saved.
• memory_search / memory_save (with --memory) — project-scoped memory shared across your AI agents.
• review_doc (with --review) — write the review document for a change: open it, patch a block by id, check every pin, read the history, restore a version, and read and answer the comments people left on the pushed document in Vibgrate Cloud. Saved under .vibgrate/review-docs/, never in the repository.

The last three groups are listed only when you ask for them. Every advertised tool schema is re-sent on every agent step, so a capability nobody enabled is a standing cost.

Prefer the hosted server over your team's scan data? Vibgrate Cloud MCP connects your assistant to Vibgrate Cloud (OAuth 2.1, 51 tools).

---

Understand any codebase

Build the graph once, query it continuously. These are recorded replays of the real CLI on sample repos — run them live.

vg build                        # index the repo (incremental; re-run after changes)
vg show src/auth/service.ts     # what this file does, calls, and is called by
vg ask "where is rate limiting enforced?"
vg impact src/db/connection.ts  # what breaks if this changes + tests to run
vg path src/api/handler.ts src/db/query.ts   # shortest call path between two files
vg tree src/server.ts           # call tree rooted at a node
vg insights                     # overview: hubs, hotspots, untested paths

The graph is byte-deterministic and reproducible — the same repo always produces the same graph on every machine.

vg share                        # make the graph committable + auto-updating for the team
vg serve                        # start Vibgrate AI Context (local-first MCP: code map + drift + version-correct docs)

---

VG Code — write the change, not just the report

VG Code is the coding agent inside Vibgrate CLI. Its search tool is the deterministic code graph — not a grep, not embeddings over chunks — and it runs on a local model or a hosted one, your choice.

vg code                                            # guided: pick a model, then describe tasks
vg code "add a --timeout flag to the scan command"

Does it write to your disk? Yes — through steps you approve, and only those. Read-only steps (search, read, list, impact) run without prompting; every edit and every command asks first. --auto runs the same loop with no prompts for CI. Without a terminal and without --auto, vg code refuses to start rather than writing unattended.

Two surfaces, one agent. vg code is the terminal surface. The VG Code panel in Vibgrate for VS Code is the graphical one, and for most people it will be the one they live in: warm sessions between tasks, chat history, inline Approve / Reject cards with diffs, checkpoints, and @-mentions. The extension does not re-implement the agent — it runs the one shipped with this CLI over --stream-json and relays your decisions to it, so terminal, editor, and CI behave the same way.

Why an agent here, and not another chat window?

• Search is the graph. search_code resolves symbols, callers, and callees from the map vg build produced — so the model gets the three functions that matter, not forty files that mention the word.
• Blast radius before the edit. graph_impact tells the model what depends on a symbol before it changes it, and vg tests knows which tests to run after.
• Version-correct library docs. library_docs pins to the version in your lockfile, so the model writes against the API you actually have.
• Invented identifiers are blocked, not flagged. Before an edit is written, its replacement body is scanned against the graph's identifier trie. A symbol the graph does not know — and that is not already local to the target file — stops the write.
• Local models are first-class, hosted models are one flag away. With a pulled model there is no account and no key, and Code Modes fit the model to the machine. When a task needs more, Vibgrate Relay supplies hosted models on your Vibgrate account — no per-provider API keys — and falls back to your local model if it is unreachable.
• It adopts the MCP servers you already have. .mcp.json (Claude Code), .cursor/mcp.json, and .vscode/mcp.json are read and merged with .vibgrate/code.json, which wins on a name clash.
• Cost is visible. A token/$ meter after each task and on /cost; vg savings reports graph-backed calls per model.

Trade-off: no model ships with the CLI, and VG Code is only as good as the model you point it at. A 7B local model is not a frontier model — it buys you privacy, offline inference, and no per-token cost. Relay buys you capacity at a per-token price. Pick the tier that matches the task; the graph grounding is the same either way.

A session, end to end

  VG Code  · graph-grounded coding · v2026.x

  ✔ Code map built
  ✔ Model catalog loaded
  ◆ Ready — ollama/qwen2.5-coder:7b · graph 48213. Describe a task, or /help.

  code › add a --timeout flag to the scan command and use it

    → search_code(query: --timeout flag scan command)
      scanCommand (function) src/commands/scan.ts:12
    → graph_impact(symbol: runScan)
      3 symbol(s) depend on runScan: …
    → edit_file(path: src/commands/scan.ts, …)
  ? Apply edit to src/commands/scan.ts? [Y/n] y
      ✔ edited src/commands/scan.ts
    → run_command(command: npm test -- scan)
  ? Run `npm test -- scan`? [y/N] y
      ✔ exit 0  … 12 passing

  ✔ added a --timeout flag to scan and covered it with tests
    +6 -1 across 1 file(s) · via ollama/qwen2.5-coder:7b

What happened, step by step:

1. The code map is built or refreshed incrementally — only changed files re-parse.
2. The model catalog loads and you pick a local model or a hosted provider. Before pulling a local model, a memory pre-flight compares its estimated footprint against available RAM/VRAM and refuses a model this machine cannot run.
3. Vibgrate Graph (vg serve) starts as a child process for the life of the session and stops when you exit. Every graph call is attributed to VG Code and the model in use.
4. The agent loops: search → read → assess impact → edit → run.
5. You approve each mutating step, or it runs unattended under --auto.
6. Edits land through a deterministic merge, so the change goes exactly where it was meant to.

Approval modes

Mode	Behavior
Interactive (default)	Read-only steps run freely. Every edit and every command asks first.
--auto	No prompts. A denylist blocks catastrophic commands — filesystem wipes, curl … | sh, force-push, sudo. For CI and scripted runs.
--single	One-shot: propose a diff and stop. No tool loop, no commands. Dry-run unless you pass --apply --yes.

--max-steps <n> caps the loop (default 24). --worktree runs the whole session in an isolated git worktree so nothing touches your main tree until you apply it.

Which model — local, or hosted through Relay

Code Modes pick a local model that actually fits this machine, checked against your real RAM, VRAM, and disk before anything downloads:

Mode	Intent
Spark	Fast, small footprint — quick edits and tight memory
Flow	Balanced default for day-to-day coding
Forge	Heavier pack when you have headroom and want more capacity

vg models                       # what's set, and what fits this machine
vg models install flow          # install the pack (--dry-run to preview)
vg models pull qwen2.5-coder:7b

Vibgrate Relay is the hosted tier that supplements those local models when a task needs more capacity than the machine has. One Vibgrate account and endpoint, a curated catalog of hosted models, per-token metering against prepaid credit — and no per-provider API keys to manage:

export VIBGRATE_RELAY_TOKEN=…   # Relay is then preferred, with local fallback
vg code --provider vibgrate-relay --model <slug>

You are not locked to it. --provider also takes ollama, lmstudio, foundry-local, llama-cpp, openrouter, litellm, openai, and together; those API keys are read from the environment only (OPENROUTER_API_KEY and friends), never passed as flags. With no --provider, vg code uses what you have already configured — Relay first if its token is set, then another hosted key, then a local model — and never dials an endpoint you did not set up. --local keeps it on-device.

Tools the agent has

Tool	What it does	Approval
search_code	Search the code graph — symbols and relations, plus a literal sweep for exact phrases	free
read_file / list_files	Read a file or line range; list files in the map	free
graph_impact	Blast radius of changing a symbol	free
library_docs	Version-correct docs for a dependency you actually have installed	free
edit_file / create_file / delete_file / apply_patch	Change the working tree	approved
run_command	Run tests, builds, anything else	approved
web_fetch / web_search	Fetch or search the public web — untrusted, secret-redacted, size-capped	approved
browser_* / read_notebook / spawn_subagent	Drive a browser, work in Jupyter notebooks, delegate a sub-task	approved
mcp__<server>__<tool>	Tools from your configured MCP servers	free if read-only, else approved

In-session commands

Command	What it does
/undo	Revert the files changed by the last task
/diff	Show the last change
/model	Switch model without leaving the session
/cost	Running token and dollar cost (local models are free)
/compact	Condense the session so far into one checkpoint recap
/help / /exit	List commands / quit

Where state lives

On disk	In the session
The code map (.vibgrate/), gitignored	Conversation and step history
Your config (.vibgrate/code.json)	The /undo stack
The edits themselves — local and git-reversible	The token/$ meter
Session store, so --continue can resume	The vg serve child process

--continue resumes your most recent session: it recaps what was already done for the model and restores /undo.

Configure once

.vibgrate/code.json — flags still override:

{
  "provider": "ollama",
  "model": "qwen2.5-coder:7b",
  "testCommand": "npm test",
  "auto": false,
  "denyCommands": ["deploy", "kubectl\\s+delete"],
  "maxSteps": 24,
  "mcpServers": {
    "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }
  }
}

Full key reference — including securityTier, capsule, and modelProfile — is in DOCS.md.

Safety

• Secrets files (.env, .npmrc, .netrc, key material) are never read into a prompt, and credential shapes are redacted from any file the agent does read.
• Under --auto, a denylist blocks catastrophic commands. Interactively you see and approve every command yourself.
• Every change is local and git-reversible. /undo reverts the last task; --worktree keeps the whole session off your main tree.
• Web and browser results are treated as untrusted content, never as instructions.

---

Measure and manage upgrade drift