Commands

vg module

Manage the optional local modules the CLI can load — relevance, the Architecture module, and the HCS engine. Install fetches an integrity-checked tarball into the Vibgrate cache; nothing in your project is touched.

Overview

Some capabilities ship as optional local modules — separately-licensed engines the CLI loads through a narrow seam rather than bundling. Three are supported today:

Module	What it powers
`relevance`	The semantic ranking kernel behind graph search, `vg ask`, and the VG Code seeds
`arch`	Architecture — architecture intelligence: classifies every function and method into a closed set of roles and purposes from its own source text, and judges the duties against a boundary policy pack. Surfaced by `vg show` and `vg show arch`, `vg scan --fail-on architecture-finding`, and the VS Code Architecture panel. Writes `graph.arch.json` beside the map
`hcs`	The engine behind `vg hcs`

relevance and arch are provisioned automatically in the background on first use (each asks for consent once at a terminal); hcs is fetched on first use of vg hcs or ahead of time. Under --local / --offline, nothing is fetched.

Usage

vg module status
vg module install arch
vg module install hcs
vg module install relevance --force
vg module remove hcs

Subcommand	Description
`status`	Installed modules, versions, whether the seam loads them, and recorded consent
`install <name>`	Install a module (`--yes` to skip the prompt, `--force` to reinstall)
`remove <name>`	Delete an installed module

What install actually does

Installation fetches the module from the npm registry as a plain tarball, verifies its integrity, and unpacks it into the Vibgrate cache. Your project is never touched, and nothing from the tarball executes at install time. The unpack stops when the tarball declares more than 10,000 entries or more than 256 MiB uncompressed. VG_MAX_ARCHIVE_ENTRIES and VG_MAX_ARCHIVE_BYTES raise those limits (0 disables that one limit). State is per-user, not per-repo, and your answer to the prompt is recorded — a decline is remembered, so nothing re-prompts on every run.

Set VIBGRATE_NO_KERNEL=1 to disable optional modules entirely: installs are refused, and commands that need an engine exit with 6 rather than silently degrading. vg module status reports the disabled state. Add --json to any subcommand for machine-readable output.

vg hcs — the command group the hcs module powers
vg doctor — one read-only pass over local setup health
Exit codes — 6 means a required module is unavailable

No live demo for this command

vg module install downloads from the npm registry and writes to a per-user cache, so it cannot be replayed as a fixed public run. The commands below are the real surface.

See a real scan run

A replay of the actual CLI running against our test repositories — live progress, real findings, a genuine DriftScore. Nothing executes in your browser.

Replay

demo@vibgrate — bash

❯ npx @vibgrate/cli scan

╭──────────────────────────────────────────╮

│ Vibgrate Drift Report │

╰──────────────────────────────────────────╯

── node-turborepo (node) .

Runtime: >=18.0.0 (6 majors behind)

Frameworks:

Turbo: 1.13.4 → 2.11.7 (1 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Dependencies:

1 current 1 1-behind 3 2+ behind 1 unknown

── @repo/admin (node) apps/admin

Frameworks:

TanStack Query: 5.104.1 → 5.104.1 (current)

React: 18.3.1 → 19.3.0 (1 behind)

React DOM: 18.3.1 → 19.3.0 (1 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Vite: 5.4.21 → 8.3.3 (3 behind)

Dependencies:

3 current 9 1-behind 3 2+ behind 4 unknown

── @repo/api (node) apps/api

Frameworks:

Express: 4.22.3 → 5.2.1 (1 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Vitest: 1.6.1 → 5.0.3 (4 behind)

Dependencies:

7 current 4 1-behind 4 2+ behind 4 unknown

── @repo/web (node) apps/web

Frameworks:

Next.js: 14.2.35 → 16.4.0 (2 behind)

React: 18.3.1 → 19.3.0 (1 behind)

React DOM: 18.3.1 → 19.3.0 (1 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Dependencies:

2 current 6 1-behind 3 2+ behind 5 unknown

── @repo/config (node) packages/config

Frameworks:

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Dependencies:

2 current 2 1-behind 5 2+ behind 0 unknown

── @repo/database (node) packages/database

Frameworks:

Prisma: 5.22.0 → 7.10.0 (2 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Dependencies:

1 current 0 1-behind 3 2+ behind 1 unknown

── @repo/types (node) packages/types

Frameworks:

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Dependencies:

0 current 0 1-behind 1 2+ behind 1 unknown

── @repo/ui (node) packages/ui

Frameworks:

React: 18.3.1 → 19.3.0 (1 behind)

TypeScript: 5.9.3 → 7.0.2 (2 behind)

React: 18.3.1 → 19.3.0 (1 behind)

Dependencies:

1 current 4 1-behind 1 2+ behind 1 unknown

── @repo/utils (node) packages/utils

Frameworks:

TypeScript: 5.9.3 → 7.0.2 (2 behind)

Vitest: 1.6.1 → 5.0.3 (4 behind)

Dependencies:

0 current 1 1-behind 2 2+ behind 1 unknown

Tech Stack

Frontend: React, React DOM

Meta-frameworks: Next.js

Bundlers: tsx, Turbo, Vite

CSS / UI: Autoprefixer, PostCSS, Tailwind CSS

Backend: Express

ORM / Database: Prisma, Prisma Client

Testing: Vitest

Lint & Format: ESLint, ESLint Prettier, ESLint React, Prettier, typescript-eslint

Services & Integrations

Auth: JWT 9.0.3

Databases: Prisma 5.22.0

TypeScript

v5.3.3 · strict ✔ · MIXED · target: ES2022

Build & Deploy

Package Managers: pnpm

Monorepo: npm-workspaces, pnpm-workspaces, turbo

Product Purpose Signals

Frameworks: react, nextjs

Evidence: 177

Top Signals:

- [heading] Dashboard (apps/admin/src/pages/Dashboard.tsx)

- [title] Revenue Overview (apps/admin/src/pages/Dashboard.tsx)

- [copy] workspace:* (packages/ui/package.json)

- [copy] ./dist (packages/ui/tsconfig.json)

- [copy] ./src/index.ts (packages/ui/package.json)

- [copy] @repo/config/tsconfig-base.json (packages/ui/tsconfig.json)

- [copy] @repo/ui (packages/ui/package.json)

- [copy] #3b82f6 (apps/admin/src/pages/Dashboard.tsx)

Unknowns:

- No pricing or billing evidence found.

- No integrations/connectors evidence found.

- No route structure evidence found.

Security Posture

Lockfile ✖ · .env ✔ · node_modules ✔

Platform

Native modules: turbo

Code Quality

Files: 36 · Functions: 183 · Avg complexity: 2.62 · Avg length: 21.13 lines

Max nesting: 2 · Circular deps: 0 · Dead code: 0%

God files: apps/admin/src/pages/Products (448 lines)

Database Schema

postgresql · 8 models · 1 enum

Models: Address, CartItem, Category, Order, OrderItem (+3 more)

Findings (16 errors, 11 warnings)

✖ Node.js runtime ">=18.0.0" reached end-of-life on 2025-04-30 (latest: 24.0.0).

vibgrate/runtime-eol in .

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in .

✖ 60% of dependencies are 2+ major versions behind in node-turborepo.

vibgrate/dependency-rot in .

✖ @types/node is 6 major versions behind (spec: ^20.11.0, latest: 26.6.4).

vibgrate/dependency-major-lag in .

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in apps/admin

✖ Vite is 3 major versions behind (current: 5.4.21, latest: 8.3.3).

vibgrate/framework-major-lag in apps/admin

✖ vite is 3 major versions behind (spec: ^5.0.12, latest: 8.3.3).

vibgrate/dependency-major-lag in apps/admin

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in apps/api

✖ Vitest is 4 major versions behind (current: 1.6.1, latest: 5.0.3).

vibgrate/framework-major-lag in apps/api

✖ @types/node is 6 major versions behind (spec: ^20.11.0, latest: 26.6.4).

vibgrate/dependency-major-lag in apps/api

✖ vitest is 4 major versions behind (spec: ^1.2.1, latest: 5.0.3).

vibgrate/dependency-major-lag in apps/api

⚠ Next.js is 2 major versions behind (current: 14.2.35, latest: 16.4.0).

vibgrate/framework-major-lag in apps/web

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in apps/web

✖ @types/node is 6 major versions behind (spec: ^20.11.0, latest: 26.6.4).

vibgrate/dependency-major-lag in apps/web

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in packages/config

✖ 56% of dependencies are 2+ major versions behind in @repo/config.

vibgrate/dependency-rot in packages/config

✖ eslint-plugin-react-hooks is 3 major versions behind (spec: ^4.6.0, latest: 7.1.1).

vibgrate/dependency-major-lag in packages/config

⚠ Prisma is 2 major versions behind (current: 5.22.0, latest: 7.10.0).

vibgrate/framework-major-lag in packages/database

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in packages/database

✖ 75% of dependencies are 2+ major versions behind in @repo/database.

vibgrate/dependency-rot in packages/database

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in packages/types

✖ 100% of dependencies are 2+ major versions behind in @repo/types.

vibgrate/dependency-rot in packages/types

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in packages/ui

⚠ TypeScript is 2 major versions behind (current: 5.9.3, latest: 7.0.2).

vibgrate/framework-major-lag in packages/utils

✖ Vitest is 4 major versions behind (current: 1.6.1, latest: 5.0.3).

vibgrate/framework-major-lag in packages/utils

✖ 67% of dependencies are 2+ major versions behind in @repo/utils.

vibgrate/dependency-rot in packages/utils

✖ vitest is 4 major versions behind (spec: ^1.2.1, latest: 5.0.3).

vibgrate/dependency-major-lag in packages/utils

╭──────────────────────────────────────────╮

│ Top Priority Actions │

╰──────────────────────────────────────────╯

1. Upgrade EOL runtime in node-turborepo

End-of-life runtimes no longer receive security patches and block ecosystem upgrades.

./.

>=18.0.0 → 24.0.0 (6 majors behind)

Impact: −10 drift points (runtime & EOL)

2. Fix security posture: no lockfile found

Without a lockfile, installs are non-deterministic. Run the install command to generate one and commit it.

Missing: package-lock.json, pnpm-lock.yaml, or yarn.lock

3. Upgrade Vitest 1.6.1 → 5.0.3 in @repo/api (+2 more)

4 major versions behind. Major framework drift increases breaking change risk and blocks access to security fixes and performance improvements.

./apps/api

Vitest: 1.6.1 → 5.0.3 (4 majors behind)

./packages/utils

Vitest: 1.6.1 → 5.0.3 (4 majors behind)

./apps/admin

Vite: 5.4.21 → 8.3.3 (3 majors behind)

Impact: −5–15 drift points

4. Reduce dependency rot in @repo/types (100% severely outdated)

1 of 1 dependencies are 2+ majors behind. Run `npm outdated` and prioritise packages with known CVEs or breaking API changes.

./packages/types

typescript: 5.9.3 → 7.0.2 (2 majors behind)

Impact: −5–10 drift points

5. Reduce dependency rot in @repo/database (75% severely outdated)

3 of 4 dependencies are 2+ majors behind. Run `npm outdated` and prioritise packages with known CVEs or breaking API changes.

./packages/database

@prisma/client: 5.22.0 → 7.10.0 (2 majors behind)

prisma: 5.22.0 → 7.10.0 (2 majors behind)

typescript: 5.9.3 → 7.0.2 (2 majors behind)

Impact: −5–10 drift points

╭──────────────────────────────────────────╮

│ Architecture Layers │

╰──────────────────────────────────────────╯

Archetype: nextjs (80% confidence)

Files classified: 24 (11 unclassified)

Folders classified: 8

apps/admin/src presentation 100% 4 files

apps/admin/src/pages presentation 100% 2 files

apps/api/src/middleware middleware 100% 2 files

apps/api/src/routes routing 100% 2 files

apps/web/src/app presentation 100% 4 files

apps/web/src/app/products presentation 100% 2 files

apps/web/src/app/products/[id] presentation 100% 1 file

packages/ui/src presentation 100% 6 files

Unclassified source (sample): 11

presentation 15 files drift ████████████████████ 100 risk high

routing 4 files drift ████████████████████ 100 risk high

middleware 2 files drift ███████▍░░░░░░░░░░░░ 37 risk moderate

config 2 files drift ░░░░░░░░░░░░░░░░░░░░ 0 risk none

shared 1 file drift ████████████████████ 100 risk high

╭──────────────────────────────────────────╮

│ DriftScore Summary │

╰──────────────────────────────────────────╯

DriftScore: 70/100

Risk Level: HIGH

Projects: 9

Classified: 8 nano · 1 micro · 0 small · 0 standard

Billable: 0.42 · 9 detected → 0.42 billable projects (micro-project pricing)

0.1 micro · 0.32 nano

These fractions add up across repositories, then round down to whole billable projects.

Score Breakdown

Runtime: ████████████████████ 100

Frameworks: ███████████▊░░░░░░░░ 59

Dependencies: ██████▌░░░░░░░░░░░░░ 33

EOL Risk: ████████████████████ 100

Scanned at 2026-10-07T12:34:03.236Z · 6.6s · 286 files scanned · 56 workspace files · 27 dirs

❯

Press Run to start.

Explore the Vibgrate CLI

vg module

Overview

Usage

What install actually does

Related

Related Documentation

See a real scan run