cli

<p align="center">
  <a href="https://vibgrate.com"><img src="https://vibgrate.com/img/vibgrate-logo-512.png" alt="Vibgrate" width="96" height="96" /></a>
</p>

<p align="center">
  <strong>@vibgrate/cli</strong>
  <br />
  Local codebase intelligence for AI coding agents — graph, drift, and version-correct docs on your machine
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/v/@vibgrate/cli?color=blue&label=npm" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/dm/@vibgrate/cli?color=green" alt="npm downloads" /></a>
  <a href="https://dash.vibgrate.com/badges/driftscore/vibgrate/cli"><img src="https://badges.vibgrate.com/vibgrate/cli" alt="Vibgrate DriftScore" /></a>
  <a href="https://vibgrate.com/cli"><img src="https://img.shields.io/badge/live%20demo-vibgrate.com%2Fcli-3FB0A4" alt="live demo" /></a>
  <a href="https://vibgrate.com/vgcode"><img src="https://img.shields.io/badge/VG%20Code-local%20or%20hosted-F59E0B" alt="VG Code — a coding agent grounded in the code graph" /></a>
  <a href="https://vibgrate.com/mcp"><img src="https://img.shields.io/badge/Vibgrate%20Cloud%20MCP-vibgrate.com%2Fmcp-8B5CF6" alt="Vibgrate Cloud MCP" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="Apache 2.0" /></a>
  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen" alt="node 22+" />
</p>

`vg` answers three questions for any repo:

1. **What is this codebase?** — A deterministic [code graph](https://vibgrate.com/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](https://vibgrate.com/whitepapers/software-risk-and-drift-scoring-methodology) under CC BY 4.0 (DOI [10.5281/zenodo.21336304](https://doi.org/10.5281/zenodo.21336304)).
3. **Can we fix it here?** — [**VG Code**](#vg-code--write-the-change-not-just-the-report), 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](https://vibgrate.com/vscode) — 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

<p align="center">
  <a href="https://vibgrate.com/cli">
    <img src="docs/demo/cli-demo.svg" alt="Animated terminal replay: npx @vibgrate/cli scan produces a 74/100 drift score, a score breakdown, and ranked upgrade priorities." width="620" />
  </a>
</p>

<p align="center">
  <sub>A real <code>vg scan</code> replay — drift score, breakdown, and ranked priorities in one command. Animation plays right here on GitHub; nothing runs in your browser.</sub>
</p>

<p align="center">
  <a href="https://vibgrate.com/cli"><strong>▶ Try the live, interactive CLI simulator →</strong></a><br />
  <sub>Step through every command (<code>scan</code>, <code>build</code>, <code>ask</code>, <code>why</code>, …) against real sample repos.</sub>
</p>

---

## Try it in 10 seconds

No install, no signup:

```bash
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:

```bash
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](https://vibgrate.com/library)** — a local-first [MCP](https://vibgrate.com/glossary/model-context-protocol) 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:

```bash
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](https://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.

```bash
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.
- **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