vg answers two 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 prioritised fix list.

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?"

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.

Tools

vg serve exposes 19 MCP tools:

• 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, 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.

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

Understand any codebase

Build the graph once, query it continuously:

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)

Measure and manage upgrade drift

vg scan                         # drift score + risk level + ranked priorities
vg scan --push                  # same, and upload to Vibgrate Cloud for trend tracking
vg baseline                     # snapshot current drift for regression gating
vg report                       # generate a report from a saved scan artifact

One scan gives you:

• Overall score (0–100) and risk level (Low / Moderate / High)
• Score breakdown — runtime, frameworks, dependencies, EOL
• Per-project detail across Node.js/TypeScript, .NET, Python, and Java
• Actionable findings ranked by likely impact
• SBOM export (CycloneDX / SPDX)
• Known vulnerabilities (opt in with --vulns) — severity, CVSS, the fixing version, and, in a git repo, who introduced them

Find known vulnerabilities and who introduced them

vg scan --vulns checks your installed dependencies against the public OSV database and reports each known vulnerability with its severity, CVSS score, and the version that fixes it — as text, JSON, or SARIF. Add --package-manifest to run it fully offline from a local advisory bundle.

vg scan --vulns                 # drift score + known vulnerabilities
vg scan --full                  # drift + vulnerabilities + a banned-dependency report

In a git repository, every finding is attributed from history: who introduced the vulnerable version, in which commit, and how long you have been exposed. Those exposure windows roll up into remediation metrics framed around the EU Cyber Resilience Act (CRA) — per-severity time-exposed and SLA breaches — so "are we fixing things fast enough?" has a number.

vg why lodash                   # who added a dependency, every version since, and any open vulnerabilities
vg bisect lodash 4.17.21        # the commit where lodash crossed a version line (e.g. reached the fix)

Detection and attribution span the whole npm ecosystem (npm, pnpm, yarn) plus pip/poetry, cargo, composer, bundler, go, pub, hex, NuGet, and Maven/Gradle — read from each project's lockfile, so it works whatever you build in.

Your AI assistant sees this too: vg serve exposes list_vulnerabilities, vuln_attribution, and an upgrade_impact tool that tells an agent what an upgrade will cost — version distance, how many files import the package, the vulnerabilities it fixes, and (online, opt in) the breaking-change notes between your version and the latest.

Track drift over time → create a free workspace

The CLI is fully useful offline. When you want trends across runs and repos — so drift becomes a metric you manage, not a surprise you discover — push scans to a Vibgrate Cloud workspace:

1. Create a workspace at dash.vibgrate.com and copy your DSN.
2. Connect and push:

VIBGRATE_DSN="vibgrate+https://<key_id>:<secret>@us.ingest.vibgrate.com/<workspace_id>" \
  vg scan --push

Upload is opt-in — nothing leaves your machine until you run --push. Store the DSN as a CI secret, never commit it.

→ Create your workspace

CI integration

Drop vg into any pipeline to turn drift scoring into a quality gate:

# GitHub Actions — drift gate + SARIF upload
- name: Vibgrate scan
  env:
    VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
  run: npx @vibgrate/cli scan --push --format sarif --out vibgrate.sarif --fail-on error

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vibgrate.sarif

Gate on drift budgets and regression relative to a baseline:

vg baseline
vg scan --baseline .vibgrate/baseline.json --drift-budget 40 --drift-worsening 5

• --drift-budget <score> fails the build if drift exceeds your budget.
• --drift-worsening <percent> fails the build if drift worsens by more than X% vs baseline.

Copy-paste CI templates live in examples/github-actions/. Azure DevOps and GitLab CI snippets are in DOCS.md.

Version-correct library docs

vg lib fetches usage docs pinned to the exact version in your lockfile — never a newer API your code can't call yet:

vg lib react                    # React docs at your installed version
vg lib express --fn middleware  # specific function reference

AI assistants connected via MCP use vg lib automatically when answering questions about library APIs in your project.

SBOM and OpenVEX

vg sbom export --format cyclonedx --out sbom.cdx.json
vg sbom export --format spdx     --out sbom.spdx.json
vg sbom delta  --from .vibgrate/baseline.json --to .vibgrate/scan_result.json --out delta.txt
vg vex                          # generate an OpenVEX document for attestation

Privacy & offline-first

• No data leaves your machine unless you run --push / vg push / vg share.
• Drift scoring reads manifests and configs only. The code graph (vg build/vg map) and a few extended scanners (code quality, database schema, UI text) read your source locally to compute structural facts and metrics — never a raw source line, and never uploaded as-is; see DOCS.md for exactly what each one reads.
• Works without login and without any SaaS dependency.
• --offline disables registry/network lookups; --package-manifest <file> feeds drift scoring a local version bundle.
• --max-privacy suppresses local artifact writes and high-context scanners; --no-local-artifacts skips writing .vibgrate/*.json to disk.

vg scan --offline --package-manifest ./package-versions.zip --max-privacy --format json --out scan.json

Add .vibgrate/ to your .gitignore — those are regenerated local outputs.

More on how Vibgrate handles code and data: vibgrate.com/security.

Quick start with AI assistants

Paste this into your AI coding tool (Claude, Cursor, Copilot, Gemini CLI, …):

Set up Vibgrate for local codebase intelligence:
1. Install: npm install -g @vibgrate/cli@latest
2. Build the graph: vg build
3. Wire your assistant: vg install
4. Ask: vg ask "what are the main entry points?"
Then explain the architecture and my top 3 upgrade priorities.

See docs/QUICKSTART-PROMPT.md for the full prompt.

Command reference

Under each set, commands are listed A–Z. A short typical path (usual order) is called out where it helps.

Code graph

Typical path: vg build → vg status → vg ask → vg impact → vg share

| Command | Description | | --- | --- | | vg ask "<question>" | Query the map in natural language | | vg build [path] | Build / update the code map (incremental, deterministic) | | vg bundle | Build an air-gapped bundle (grammars + graph + library catalog) | | vg code "<instruction>" | Propose a graph-grounded code edit (dry-run by default; --apply --yes to write) | | vg embed | Precompute the semantic index for instant vg ask | | vg export | Export the map (json / ndjson / graphml / dot / cypher / md / html / SBOM) | | vg facts <file> | Deterministic facts for a node (contracts, invariants) | | vg guide <file> | Cited standards / practices for a node (free pack) | | vg impact <file> | What breaks if you change it — and the tests to run | | vg install / vg uninstall | Wire (or remove) Vibgrate AI Context + skill in your AI assistant (--detect, --all, --list) | | vg lib <package> | Version-correct, drift-annotated library docs | | vg map / vg hubs / vg areas / vg oddities | Map insights: overview, most-depended-on code, natural groupings, cross-area smells | | vg models | Code Modes (Spark / Flow / Forge) + local fleet (Ollama / LM Studio / gguf); install / pull by default (--dry-run to preview) | | vg path <from> <to> | How A connects to B (shortest path) | | vg savings | Local report of tokens/$ saved vs a grep baseline (estimates) | | vg watch | Rebuild the map when files change | | vg serve | Start Vibgrate AI Context (local-first MCP: code map + drift + version-correct docs) | | vg share | Make the graph committable + auto-updating for your team | | vg show <file> | Explain a node: what it is, what it calls, what calls it | | vg status | Cache/freshness, counts, staleness | | vg tests <file> | Which tests cover a node | | vg tree <file> | Call tree rooted at a node | | vg unknowns | What the graph cannot resolve, ranked by blast radius |

Diagnostics, IDE & runtime

Typical path: vg doctor → vg lsp → vg daemon

| Command | Description | | --- | --- | | vg daemon | Local workspace daemon for multi-root graph sessions (IDE / agents): status, ensure, publish, query, impact, … | | vg doctor | Read-only diagnosis: config, credentials (redacted), map freshness, hosted reachability, MCP launch | | vg lsp | Language server (stdio) — engine behind Vibgrate for VS Code and other thin IDE clients | | vg policy | Show production context-policy pin; vg policy verify <file> for signed learning patches |

Drift scoring & supply chain

Typical path: vg init → vg scan → vg baseline → vg report → vg fix

| Command | Description | | --- | --- | | vg baseline [path] | Create a drift baseline | | vg bisect <package> <constraint> | The commit where a dependency crossed a version line (--assert to gate CI) | | vg drift | What is outdated across dependencies (offline; --online for currency) | | vg evidence | Signed, reproducible regulatory evidence (regime-neutral; CRA first) | | vg fix | Ranked, risk-tiered upgrade plans from the hosted planner — then apply the one you choose | | vg init [path] | Initialise config and .vibgrate/ | | vg report | Generate a report from a scan artifact | | vg sbom export / delta / vex | Export CycloneDX/SPDX SBOM, diff two artifacts, or emit an OpenVEX document | | vg scan [path] | Scan for upgrade drift | | vg scan --full | Comprehensive scan: drift + vulnerabilities + a banned-dependency report | | vg scan --push | Scan and push results to Vibgrate Cloud | | vg scan --vulns | Also detect known vulnerabilities (OSV; offline via --package-manifest) | | vg update | Check for and install updates | | vg why <package> | Who introduced a dependency, its version history, and any open vulnerabilities |

Workspace auth & cloud upload

Local scoring does not require this — nothing leaves your machine until you push.

Typical path: vg login → vg dsn create → vg push → vg logout

| Command | Description | | --- | --- | | vg dsn create | Generate a DSN token | | vg login / vg logout | Authenticate the CLI with your Vibgrate workspace (or clear stored credentials) | | vg push | Upload scan results to Vibgrate Cloud |

vg scan [path] [--vulns] [--full] [--format text|json|sarif|md] [--out <file>] [--fail-on warn|error] \
  [--offline] [--package-manifest <file>] [--no-local-artifacts] [--max-privacy] \
  [--drift-budget <score>] [--drift-worsening <percent>] [--baseline <file>]

Full flag and configuration reference: DOCS.md · vibgrate.com/cli.

Why teams adopt Vibgrate

Most systems don't fail all at once — they accumulate upgrade debt and architectural drift silently until migrations become expensive. vg makes that debt measurable and repeatable — the practice we call Code Drift Intelligence — and gives AI assistants the local context they need to be useful:

| Mode | What you get | Best for | | --- | --- | --- | | One-off scan | Fast snapshot of drift score, lag, and findings | Audits, due diligence, migration planning | | CI-integrated scan | Continuous drift signal, SARIF annotations, regression guardrails | Keeping upgrade debt under control long-term | | MCP + graph | AI assistant with real-time, offline codebase context | Day-to-day development, code review, refactoring |

Recommended rollout: vg build + vg install now, add vg scan to CI this week.

Requirements

• Node.js 22+
• macOS, Linux, Windows

Command name conflicts

vg is short and occasionally conflicts with other tools (virtualgo, vugu, the oh-my-zsh git verify-commit alias, custom shell aliases, etc.).

vibgrate is an identical alias — same binary, same flags, same behaviour. If vg is taken on your system, use vibgrate everywhere instead:

vibgrate scan          # same as: vg scan
vibgrate build         # same as: vg build
vibgrate serve         # same as: vg serve

When @vibgrate/cli is installed, it registers both bin entries unconditionally. If it detects at install time that vg is already claimed by another tool, it prints a one-line notice pointing you to vibgrate.