Local-first MCP server: version-correct library docs, code map, and offline drift for your repo.
com.vibgrate/ai-context โ Model Context Protocol (MCP) Server
This local-first MCP server provides version-correct library documentation and codebase intelligence for repositories on your machine. It emphasizes building a code map and measuring offline drift, along with dependency graph and related dependency management context.
What is this codebase? โ A deterministic code graph: call trees, import paths, impact surfaces, dependency facts.
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).
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.
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.
Windows installation
Windows is supported with Node.js 24 or newer. PowerShell is the preferred shell for the Windows installer:
powershell
irm https://vibgrate.com/install.ps1 | iex
If you prefer npm, install the CLI globally:
powershell
npm install -g @vibgrate/cli
For a one-off run without changing PATH, use:
powershell
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:
powershell
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 โ 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:
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.
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.
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, 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 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, 14 read-only 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.
node-turborepo/build โ vg build maps a pnpm monorepo.
bash
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
node-turborepo/ask โ vg ask returns cited nodes, not a chat essay.
node-turborepo/impact โ blast radius of changing a hub before you edit.
The graph is byte-deterministic and reproducible โ the same repo always produces the same graph on every machine.
bash
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.
bash
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
text
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:
The code map is built or refreshed incrementally โ only changed files re-parse.
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.
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.
You approve each mutating step, or it runs unattended under --auto.
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
bash
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:
bash
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
Known vulnerabilities (opt in with --vulns) โ severity, CVSS, the fixing version, EPSS when the advisory data already has it, 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. JSON also includes epss, epssPercentile, and kev when the advisory data already carried them; a missing score is omitted, never written as 0. Add --package-manifest to run it fully offline from a local advisory bundle. Offline and manifest scans do not contact an EPSS service. In npm, pnpm, and yarn projects it also checks the packages your dependencies pull in, read from the lockfile, and names the path to each one. A missing or invalid manifest exits 1 and does not scan. The manifest shape and the error text are in DOCS.md.
SARIF writes one result per package and advisory (vg scan --vulns --format sarif). Every result includes partialFingerprints["vg/finding-id/v1"], so an unchanged finding keeps the same code-scanning alert. The advisory's own id is the primary id. CVE and other aliases stay on that result. A second code-scanning alert is expected when the scan kept two advisory ids, including when those ids list each other as aliases. Field layout, result order, and what the fingerprint is made from: DOCS.md and DOCS.md.
JSON (vg scan --vulns --format json, and .vibgrate/scan_result.json) writes one finding for a package and version when those ids alias each other, including through a third id. The finding id is the lowest CVE in the group when any linked id is a CVE, and the lowest advisory id when none is. One advisory keeps its own id. aliases lists the other ids, sorted. --offline --package-manifest groups the same way. The id rule is in DOCS.md.
bash
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 per-severity time-exposed and SLA-breach metrics, framed around the EU Cyber Resilience Act (CRA) โ so "are we fixing things fast enough?" has a number.
That answers the question about this checkout. For the question a regulator asks โ which shipped products contain it โ see Vibgrate Evidence below.
bash
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, pub, hex, NuGet, and Maven/Gradle โ read from each project's lockfile, so it works whatever you build in. Go is matched from direct require lines in go.mod, and from an // indirect module that provides a Go 1.24 tool package. Pseudo-versions and +incompatible tags are compared as described in DOCS.md.
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.
A scanner tells you about the code in front of you. A regulator asks about the code you shipped โ eighteen months ago, at version 3.2.1, into Germany and France, still in its support window. Vibgrate Evidence answers that question as a signed artifact a third party can verify offline, with no account and no network.
It produces evidence, not a verdict. It will not tell you that you are compliant, and it is not legal advice. It gives you a defensible, reproducible answer and the audit trail behind it; the determination and the filing stay yours.
bash
vg evidence init --regime cra # who files, and to which coordinator
vg evidence product add "Acme Gateway" --markets DE,FR --in-scope
vg evidence release acme-gateway 3.2.1 --from sbom.cdx.json --ship-date 2025-02-14
vg evidence exposure CVE-2025-12345 --bundle ./ev # signed answer, exit code for CI
Why freeze a manifest instead of scanning again?
Ships are immutable; your tree is not.exposure matches against the manifest frozen at ship time, not HEAD. Re-scanning today tells you what you would ship now, which is not the question asked.
It refuses to guess. A product bound to a release with no frozen manifest comes back undeterminedwith a reason, never a confident-looking not affected. That distinction is the whole value of the artifact.
Jurisdiction-neutral by design. Reporting duties are modeled as regimes: the EU CRA (--regime cra, applies from 11 September 2026) and DORA incident reporting (--regime dora-incident) ship today. A new jurisdiction is a regime profile, not a new command or a new tool.
No model touches a figure. Nothing in the evidence path is generated by a language model. Every number is computed from frozen manifests and advisory data.
Offline end to end.--offline with a local advisory file needs no network, and vg evidence verify works on a machine that has never heard of Vibgrate.
Trade-off: the answer is only as good as the manifests you froze. Evidence cannot reconstruct what you shipped before you started recording it โ a release you never froze is undetermined, permanently. The value compounds from the day you start, which is the argument for starting now rather than in September.
The lifecycle
Step
Command
What it does
1. Set up
vg evidence init
Org, coordinator CSIRT, and the person with filing authority
2. Register
vg evidence product add
A product with digital elements โ markets, classification, scope rationale
3. Freeze
vg evidence release
Pin a shipped version to an immutable component manifest, from an SBOM, a scan, or what BuildKit built
4. Ask
vg evidence exposure <vuln>
Which shipped products contain it, at which versions, in which markets, still in support
5. Prove
vg evidence verify <bundle>
Re-check the signed answer offline, on any machine
Between those: vg evidence readiness is a deterministic gap report against the regime's obligations, vg evidence regimes lists the regimes and their clocks, vg evidence drill runs a timed rehearsal against a simulated advisory, vg evidence watch joins the CISA KEV catalog to your frozen manifests, vg evidence pack builds the submission pack a human pastes into the reporting platform, and vg evidence export writes an air-gapped bundle of everything. What regimes, readiness, and drill read, and a local dry-run that finishes before any upload, is in DOCS.md.
Freeze a container release from what the build wrote
If the shipped artefact is a container image, the build already produced the facts a manifest needs. vg evidence release can read them directly rather than have someone type them in:
An SBOM passed with --from, or attached to the image, has to be valid CycloneDX or SPDX JSON. A file that is truncated, not JSON, or missing a required field exits 1. The message names the file and the format it expected, and says to regenerate the SBOM. It does not include the document. A component or package missing name fails the command instead of being dropped.
--image <ref> asks Docker for the image digest, its org.opencontainers.image.* labels, and the provenance and SBOM attestations attached to it; the attached SBOM becomes the manifest. It runs docker image inspect and docker buildx imagetools inspect, and the second contacts the registry when the reference is not present locally. Without a daemon, pass the same facts as files: --buildkit-metadata build.json for the digest and build reference, --provenance <file> for a SLSA attestation (source repository, commit, base images), and --from <file> for a CycloneDX or SPDX SBOM, bare or as an attestation. The result is recorded under build in the frozen manifest. A --digest that contradicts the build is an error, and attestation signatures are recorded as unverified โ vg has no registry trust root, so verify them with cosign.
What is in a bundle, and what "verified" means
--bundle <dir> writes result.json, a DSSE/Ed25519 in-toto attestation over it (evidence.intoto.jsonl), a VERIFY.md a third party can follow, and โ with --tsa <url> โ an RFC 3161 trusted-timestamp token (timestamp.tsr).
vg evidence verify reports one of three honest states, and the middle one matters:
State
Meaning
verified
Signature checks, the signer is pinned to a trust root you supplied with --pub, and the result digest still matches
unverified
Cryptographically intact and unmodified, but the signer is not pinned โ real, and not yet trusted by you
failed
Bad signature, or a result.json that no longer matches what was signed
A truncated, invalid, or unreadable bundle is not one of those states. vg evidence verify exits 1 and tells you to restore the bundle or re-create it with vg evidence exposure --bundle. The message does not include the file's contents.
Exit codes make it a CI gate: 0 no exposure ยท 2 exposure found ยท 3 undetermined, needs manual review ยท 1 operational error.
Evidence state lives in .vibgrate/evidence/. The Ed25519 signing key is minted on first use at .vibgrate/attest-key.pem (mode 0600, with a .pub beside it) unless you point at your own with VG_ATTEST_KEY โ back it up, and never commit it.
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:
java-spring/budget โ vg scan --drift-budget 60 as a CI gate (this recording exits 0). Live simulator.
The fastest start on GitHub is one command. It writes .github/workflows/vibgrate.yml, which scans every pull request with the vibgrate/cli Action and uploads SARIF to GitHub Security. No Vibgrate account is needed:
bash
vg init --ci github
Prefer to write it yourself? The same workflow is one step with the vibgrate/cli Action:
yaml
-uses:actions/checkout@v4-uses:vibgrate/cli@v1with:upload-sarif:truemax-score:40# optional: fail the job when DriftScore is above 40
Drop vg into any pipeline to turn drift scoring into a quality gate:
--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.
--fail-on-epss <threshold> fails the build when any advisory EPSS score is at or above the threshold, a probability from 0 to 1. A score equal to the threshold fails. A missing score is not compared and is not treated as 0. The flag replaces failOnEpss in .vibgrate/config.yml or vibgrate.config.json. It reads advisories from vg scan --vulns or vg scan --full. See DOCS.md.
--summary-out <file> writes a small JSON summary (driftScore, riskLevel, change since --baseline, and the driftBudget verdict) that a CI step can read, even when a gate fails the run. driftBudget is null when no budget is set. --drift-budget and --drift-worsening are recorded with sourceflags. An unmeasured score is null, never 0. The full artifact carries the same drift.* fields plus the per-component scores: DOCS.md.
--junit <file> writes a deterministic JUnit XML summary of findings and those gates, next to --format (JSON or SARIF). The exit code is unchanged; see DOCS.md.
A scan with --baseline also records findings that already appear in the snapshot (rule, location, and id). The text report prints the count, SARIF lists the same ids as suppressions, and those findings stay in the report.
Copy-paste CI templates live in examples/github-actions/. When the job fails, when warn mode stays green, which versions to pin, and how a DriftScore badge is filled in: examples/github-actions/README.md. Azure DevOps and GitLab CI snippets are in DOCS.md.
Version-correct library docs
vg lib <pkg> prints usage docs for one library. When a lockfile in the project root lists that package, the version label is that pin. Which files are read, and what happens when the pin is missing, the install disagrees, or the catalog fetch fails: DOCS.md.
bash
vg lib react
AI assistants connected via MCP use vg lib automatically when answering questions about library APIs in your project.
SBOM and OpenVEX
strapi/sbom โ vg sbom export --format cyclonedx --out sbom.cdx.json. An inventory, not a compliance determination. Live simulator.
vg sbom export writes an inventory, not a compliance determination. CycloneDX component type is application on the metadata component and library on every dependency row, including a container image. SPDX primaryPackagePurpose is omitted. The mapping, the gaps (OS packages, image contents, Terraform resources), and short fixture examples are in DOCS.md.
vibgrate:scope on each component is direct or transitive. A development dependency sets CycloneDX component scope to excluded and an SPDX DEV_DEPENDENCY_OF relationship. An optional dependency sets scope to optional and OPTIONAL_DEPENDENCY_OF. The mapping, including fields the export omits, is in Dependency scope.
Match a component on its package URL (purl in CycloneDX, the purl externalRef in SPDX). Scan JSON uses the same coordinates (projects[].type, dependencies[].package, resolvedVersion, and extended.vulnerabilities.packages[]) and does not repeat the purl string. These files have no CPE field. The CLI does not invent one, and a CPE from another cataloger does not replace the purl. Fields and a local example: DOCS.md.
When a lockfile records package digests, CycloneDX hashes and SPDX checksums list them sorted by algorithm name, then by digest value. A package with no recorded digest omits the array. A scan dependency has no digest field. serialNumber, documentNamespace, projectId, and solutionId are identifiers. Fields and a local example: DOCS.md.
--format is cyclonedx (the default) or spdx. How the same scan differs between those files โ purl placement, the dependency graph, licenses, tool metadata, and the document id โ is in Choosing CycloneDX or SPDX.
Review a change
Vibgrate Review reads the current change against the declared architecture and security-control policy. It reports change integrity, not a proof of security.
vg review findings-from-diff prints the deterministic vg.review.findings.v1
document (blast-radius and architecture-policy correctness rows plus security
scanners) and writes .vibgrate/review-propose-handoff.json.
The JSON field list, every kind, the sort order, a captured example, and the
failure exits are in DOCS.md.
vg review propose <id> attaches a PatchIR dry-run โ --model is
relay:<slug> (hosted Review) or spark | flow | forge (local Code Mode).
Lookup is the current change set, then --findings JSON, then that last-run
handoff; pass the same --base / --in-place / --diff as findings-from-diff
when you want that change set explicitly. It writes nothing unless you pass
--apply --yes on a topic branch.
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 does not contact package registries and does not upload results. --package-manifest <file> feeds drift scoring, and with --vulns known vulnerabilities, from a local JSON or ZIP manifest. A missing or invalid manifest exits 1. The same tree and the same manifest keep the same findings order and advisory ids. See DOCS.md.
--max-privacy suppresses local artifact writes and high-context scanners; --no-local-artifacts skips writing .vibgrate/*.json to disk.
vg code --local keeps model inference on-device: a local model, the local graph, no hosted call and no model-catalog fetch. The agent's own web tools stay available and, like every network step, are approved by you before they run.
vg code never reads a secrets file into a prompt, and redacts credential shapes from files it does read.
vg evidence runs locally: --offline with a local advisory file needs no network, and vg evidence verify checks a bundle on a machine with no account and no connection. Nothing reaches Vibgrate Cloud until you run vg evidence push. vg evidence regimes, vg evidence readiness, and vg evidence drill stay on that local path โ profiles shipped in the CLI, and .vibgrate/evidence/ for the gap report and the drill. The dry-run is in DOCS.md.
Paste this into your AI coding tool (Claude, Cursor, Copilot, Gemini CLI, โฆ):
code
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.
vg ask answers from the local map. The question and your code stay on this machine. --offline skips the optional module fetches and this process's embedding-model download. See What stays local / when the network is used.
Command
Description
vg ask "<question>"
Query the map in natural language
vg build [path]
Build / update the code map (incremental, deterministic). --attest signs that map; --verify checks the signature against the map on disk. Flags, the key, and the failure text are in DOCS.md. --policy hexagonal-v1|layered-v1|vertical-v1 picks the boundary rules the architecture module evaluates (default from .vibgrate/architecture.toml, which may also carry your own [[overlay]] rules); --init-policy writes a first draft of that file from what the build classified (the packs and overlays are described in docs/architecture-policies.md)
vg bundle
Build an air-gapped bundle (grammars + graph + library catalog)
vg code ["<instruction>"]
Graph-grounded coding agent โ local or hosted model, every edit and command approved (--auto for CI, --single for a one-shot diff)
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 locale
Manage your app's translations โ locale projects, keys, and translations in Vibgrate Cloud (push / pull / status; vg localize is an alias)
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 show arch
Open a local architecture map: workspace packages first, then a column slice (UI โ service โ store). Loopback; --focus <symbol>, --no-open
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
There is no vg attest-actions command. vg attest and vg verify are retired names for vg build --attest and vg build --verify.
vg build --attest writes a DSSE in-toto statement to .vibgrate/attestation.intoto.jsonl (override with --attestation <file>). The key is --attest-key <path>, else VG_ATTEST_KEY, else .vibgrate/attest-key.pem. The first run with no key at that default path mints an Ed25519 key (mode 0600, and a .pub file next to it) and tells you to keep it and gitignore it. A path you name that is missing is a usage error. A key that is not Ed25519 is rejected. Commit the attestation. Do not commit the private key.
vg build --verify checks that file against the map already on disk. It does not rebuild in order to check the signature, and it does not replace the map. The same command also rebuilds the map in memory to confirm the build is deterministic. --pub <path> pins the signer. Without it, a good signature means the file was not altered, not that you trust the signer. A missing file at the default path is reported as absent. Naming an attestation file that is not there fails and points at vg build --attest.
Signing and checking are local cryptography. They do not upload. git is used only while signing, and only when it works, to record the commit. vg build --attest is still a build: pass --offline or --local when that build must not download the Architecture module or an embedding model. Full inputs, outputs, and every failure line: DOCS.md.
Run the pipeline over a file by hand โ the debug path, not part of normal use
vg serve retrieve <hash>
Expand a compression marker back to the original, or a slice of it (--grep, --lines, --head, --tail, --json-path)
Holistic Code Specification (vg hcs)
Deterministic code facts for Rust, Ruby, PHP, Dart, Swift, Scala, C++, COBOL, and VB6 โ one NDJSON line per fact, reproducible on any machine, so a fact stream is something you can commit, diff, and gate CI on. Extraction is incremental by default: re-running over an existing stream costs only the delta.
All HCS computation runs in an optional, separately-licensed engine module that executes in a local WASM sandbox โ no network calls, no process spawns. It is fetched on first use, or ahead of time with vg module install hcs. When it is unavailable, every vg hcs command exits 6 โ never 2, so a CI gate can't mistake "engine missing" for a verdict.
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 review
Vibgrate Review โ architecture + security-control review of the current change, locally (--in-place, --local, --loop). Deterministic blast-radius findings from the code graph via vg review findings-from-diff; vg review propose <id> attaches a PatchIR dry-run (same --base / --in-place / --diff, --findings, or .vibgrate/review-propose-handoff.json). One decision (pass / needs_review / fail / undetermined) in a signed receipt (Ed25519 over the receipt digest; vg review verify <receipt.json> checks it offline); protected findings cannot be blessed into a pass. Reports change integrity, not a proof of security. Builds or refreshes the code map itself when it is missing or stale (--no-auto-build opts out)
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
vg why <file:line>
The commit that last changed a line, and the VG Code session that wrote it (opt in with vg review trailer on)
vg review trailer push
Share the VG Code sessions behind your commits with Vibgrate Cloud, so vg why <file:line> --cloud works for teammates
Workspace auth & cloud upload
Local scoring does not require this โ nothing leaves your machine until you push.
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. See how it lands for teams and enterprises, or compare it with what you already run: vs Renovate ยท vs Dependabot ยท vs Snyk.
AI assistant with real-time, offline codebase context
Day-to-day development, code review, refactoring
VG Code
A coding agent grounded in the graph โ terminal or VS Code panel, local model or Relay, governed edit by edit
Making the change, not just planning it
Recommended rollout: vg build + vg install now, add vg scan to CI this week, try vg code on one small task.
Known limits
Drift and risk scores are estimates, computed from manifests, lockfiles, and public advisory data. They are a prioritization signal, not a compliance determination or a certification.
VG Code quality tracks the model you choose. No model ships with the CLI. A small local model handles mechanical edits well and struggles with cross-cutting design changes; vg models tells you what fits this machine, not what will do the job. Reach for Relay or another hosted model when the task is bigger than the machine.
Guided vg code needs a terminal. In CI, pass an instruction plus --auto (or --mock) โ the interactive picker never appears, and the agent refuses to run unattended without it.
The map is the ceiling. Anything the resolver could not tie to a definition is invisible to search_code and graph_impact. Run vg unknowns to see what the graph is missing, ranked by blast radius.
--auto is a denylist, not a sandbox. It blocks known-catastrophic commands; it does not confine the agent. Run untrusted instructions in a container, or under --worktree with --security-tier L1.
--verify re-runs your tests; it does not prove correctness. Failures are fed back for a repair attempt. Passing tests mean passing tests.
Vulnerability data is only as current as its source.--vulns reports what OSV knows at scan time; offline runs report what is in the bundle you supplied.
Vibgrate Evidence produces evidence, not a compliance determination. It supports your obligations under a regime; it does not decide that you meet them, does not certify anything, and is not legal advice. The filing is yours.
Evidence cannot look backwards. Exposure is answered from manifests frozen at ship time. A release you never froze stays undetermined โ there is no way to reconstruct it after the fact.
vg evidence watch surfaces a KEV listing, not a determination. Whether a vulnerability is "actively exploited" for the purposes of a filing is your call, not the tool's.
vg evidence verify does not re-verify the TSA certificate chain. It confirms the RFC 3161 token's imprint binds to result.json and surfaces the trusted time. For the full chain, use openssl ts -verify -in timestamp.tsr -data result.json -CAfile <tsa-ca.pem>.
Requirements
Node.js 24+
macOS, Linux, Windows
VG Code additionally needs a model: a local runtime (a Code Mode pack, Ollama, LM Studio, or a GGUF on disk), a Vibgrate Relay token, or an API key for another hosted provider. Run vg models to see what fits this machine.
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 behavior. If vg is taken on your system, use vibgrate everywhere instead:
bash
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.
vg review โ did this change move the system toward its declared architecture, or weaken a security control? Runs locally from the code map; the receipt, not the repository, is what gets pushed
vg evidence โ freeze shipped releases, then answer "which shipped products contain this vulnerability?" as signed, offline-verifiable evidence. Jurisdiction-neutral regimes, EU CRA first