Vgxness

VGXNESS is an installable, local-first governance OS and MCP/CLI control plane for existing coding agents. It governs SDD artifacts, local memory, runs, permissions, skills, provider setup, and verification evidence while OpenCode, Claude Code, and future adapters keep executing provider-native.

Release status and license

This package is proprietary software. The npm package ships inspectable JavaScript (dist/) so Node can run it, but it is not open-source licensed and may not be redistributed unless you have written permission. See LICENSE.

OpenCode is the primary supported provider. Claude Code setup support is secondary/preview guidance. VGX-managed OpenCode and Claude provider configuration is user-global only; provider config writes require explicit CLI confirmation.

VGXNESS is versioned from package.json. The latest full project health audit is the historical v1.14.x snapshot, which documents the implemented CLI/MCP/SDD governance control plane, OpenCode-first workflow, release-readiness checks, and the remaining execution/recovery gaps at that point in time. v1.10.x and v1.9.1 remain historical validation evidence for those releases.

Requirements

• Bun >= 1.3.14 for the installed vgxness/vgx CLI/MCP runtime and repository verification
• Node.js >= 22 for repository development, build, test, and helper-script tooling
• A platform supported by Bun SQLite (bun:sqlite) for runtime storage

Bun is the canonical installed runtime and verification tool. Node remains development/build/test tooling for TypeScript, node:test, and selected helper scripts; package consumer metadata (bin and files) remains part of the npm install contract.

Bun-first staged toolchain

Use Bun for development verification and CI parity:

bun install --frozen-lockfile
bun run check:bun-lock
bun run verify:typecheck
bun run verify:test
bun run verify:test:bun-storage
bun run verify:bun-sqlite
bun run verify:package
bun run package:bun:evidence -- --require-pass

bun run verify

Package evidence is Bun-only after the npm publication bridge retirement:

Area	Current owner	Why
Typecheck, tests, Bun SQLite probe, package evidence	Bun	This is the canonical CI verification path.
Package artifact and isolated install smoke	bun run package:bun:evidence -- --require-pass	It creates/inspects the artifact, validates package contents, installs in an isolated Bun environment, checks both CLI bins, and records Bun runtime identity.
Installed CLI runtime	Bun >=1.3.14	Published vgxness/vgx execute dist/cli/bun-bin.js, which records optional runtime evidence and then imports the CLI.
Lockfile review	bun.lock	The npm bridge lockfile has been retired; do not treat that as dropping npm consumer installability.

Do not remove npm package metadata, bin, or files as part of bridge cleanup; those remain the package consumer contract. The product runtime engine is engines.bun, not engines.node.

When package.json dependency specifiers change, refresh and review bun.lock intentionally. To check manifest/lock drift without mutating node_modules, run:

bun run check:bun-lock

The manual compatibility probe remains useful when diagnosing Bun/package-manager behavior:

npm run probe:bun
npm run probe:bun -- --yes   # mutates dependencies only after explicit consent

Runtime SQLite readiness is proven only with bun:sqlite. bun run verify:bun-sqlite copies the source migrations into a temporary directory, applies them against a temporary database, checks foreign keys, busy timeout, FTS/search, transaction rollback, integrity, and cleanup. Node.js remains development/build/test tooling, but real local SQLite storage is supported through the Bun runtime path.

Bun package evidence

To collect diagnostic package artifact and isolated install-smoke evidence without publishing, run:

bun run package:bun:evidence

Diagnostic mode may emit status: incompatible and still exit 0 so maintainers can inspect JSON. For release-readiness, require a passing result explicitly:

bun run package:bun:evidence -- --require-pass

The probe is the authoritative release evidence path for package contents. It does not invoke registry publication commands, writes optional JSON only where requested, records publicationAttempted: false, and reports releaseReadiness diagnostics when evaluating the gate.

It protects:

• package metadata, files, bin, license, Bun engine, README/LICENSE, docs, migrations, and shipped seed assets;
• absence of workspace-only content such as src/, test/, .opencode/, openspec/, source maps, SQLite/database files, and OS junk;
• both installed commands: vgxness --help and vgx --help.

Release-candidate checklist, still non-publishing:

1. bun install --frozen-lockfile completes on a clean checkout.
2. bun run check:bun-lock passes.
3. bun run verify:typecheck, bun run verify:test, bun run verify:test:bun-storage, and bun run verify:bun-sqlite pass.
4. bun run package:bun:evidence -- --require-pass passes on supported CI OSes.
5. JSON evidence shows status: pass, artifact/install smoke pass, no retired bridge scripts, no package-lock.json, publicationAttempted: false, and releaseReadiness.status: pass.
6. Version, release notes, proprietary license boundary, and rollback criteria are reviewed.
7. Publishing remains a separate explicit human-approved process.

This checklist does not run npm publish, bun publish, registry dry-runs that contact a registry, registry token use, provenance upload, release creation, or dist-tag mutation.

Temporary rollback if Bun package evidence misses a release regression

Rollback is release-impacting and temporary. Use it only when Bun package evidence misses a package regression, downstream install verification fails in a way Bun did not catch, or a release candidate needs short-lived npm bridge validation while the Bun evidence gap is investigated.

Restore these bridge elements from the previous known-good main commit:

• package-lock.json
• package scripts: prepack, package:release-check, package:dry-run, and package:smoke:install
• deleted helper scripts: scripts/validate-package-release.mjs and scripts/smoke-tarball-install.mjs
• npm validation wiring and tests that enforced the bridge
• the .github/workflows/node22.yml npm-publication-bridge job and its artifact/install-smoke steps

Do not publish during rollback verification unless a separate explicit approval covers publication. Follow up with an investigation or SDD change before retiring the bridge again.

Legacy Bun probe commands

These commands are retained for compatibility investigation, not as a replacement for bun run verify:

npm run check:bun:typecheck
bun run typecheck
bun run build
bun run package:bun:evidence

Install globally

npm install -g vgxness
vgxness --help
vgx --help # compatibility alias

First setup with OpenCode

Preview the setup plan:

vgxness init

vgxness init is read-only by default, including in TTYs; apply still requires explicit --yes. For a copyable bootstrap and diagnostic path after installing the package globally:

vgxness setup plan
vgxness setup apply --yes
vgxness doctor
vgxness status --project <project> --change <change>
vgxness next --project <project> --change <change>
vgxness sdd continue --project <project> --change <change>

Stable defaults are: package vgxness, provider opencode, global user data DB, user-global OpenCode config ($HOME/.config/opencode/opencode.json), and mcp-plus-agents mode. VGX-managed OpenCode and Claude provider configuration is user-global only; runtime VGXNESS state remains project-aware through --project, --change, workspace, and database context. Existing project-local provider files such as .opencode/, opencode.json, .mcp.json, .claude/, and CLAUDE.md remain untouched by VGXNESS setup. They may still affect OpenCode or Claude behavior externally, but VGXNESS treats them as external/manual diagnostics and will not repair, write, back up, or delete them. The generated MCP command for the global DB default is:

vgxness mcp start

Apply only after reviewing the plan:

vgxness setup apply --yes

vgxness setup plan and vgxness setup status are human-readable and do not write provider config by default; local VGXNESS store initialization may occur when a command needs the selected SQLite store. vgxness doctor, vgxness status, vgxness next, vgxness sdd status, vgxness sdd next, vgxness sdd continue, and vgxness sdd accept-artifact are also human-readable by default. Pass --json when you need parseable automation output. vgxness setup apply --yes is the explicit provider-config write path.

The daily SDD happy path is an OpenCode conversation with the installed VGXNESS MCP server and provider-native hidden SDD subagents. VGXNESS supplies the governance state and guardrails; OpenCode executes the agent loop. Use CLI commands for bootstrap, setup, diagnostics, recovery, fallback, and scripting: status, next, and sdd continue inspect state and print read-only continuation guidance; resume helps inspect interrupted work. In the normal organic flow, proposal acceptance is the first mandatory human continue gate; after that, spec -> design -> tasks can be drafted without separate confirmations, then VGXNESS asks before apply/implementation. sdd accept-artifact records explicit human-only acceptance when a real gate applies, and sdd reopen-artifact returns rejected artifacts to draft.

Copy this prompt into OpenCode for normal daily SDD work:

Continue VGXNESS SDD for project <project> and change <change>.
Use the VGXNESS MCP tools to inspect status/readiness/artifacts, then delegate phase work to the exact hidden SDD subagent when needed.
Save draft artifacts when appropriate and report evidence, tests, blockers, and the next human decision.
Treat proposal acceptance as the first mandatory human continue gate; after that, draft spec/design/tasks without separate confirmations, then ask before apply/implementation.
Do not accept or reopen artifacts for me; ask before provider/global config, git/publish, destructive, external, privileged, install, network, secret-sensitive, or official archive actions.

Code runtime status

The experimental vgxness code runtime and principal OpenTUI code surface have been removed and are not the default product direction. Continue SDD work in OpenCode through VGXNESS MCP, and use the safe CLI commands above for diagnostics and recovery. Reintroducing a first-party coding-agent runtime would require a separate accepted SDD change.

Safety model

• Preview, status, and plan commands do not write provider config; local VGXNESS store initialization may occur where the command needs SQLite-backed state.
• VGX-managed OpenCode and Claude provider config writes are user-global only and require explicit --yes confirmation.
• Runtime VGXNESS state remains project-aware; project-local provider files are read-only external/manual diagnostics and may still affect provider behavior outside VGXNESS.
• Setup/status TUI surfaces are read-only setup, diagnostics, recovery, and fallback surfaces; daily SDD progression stays in OpenCode with VGXNESS MCP and provider-native execution.
• SDD artifacts are SQLite-backed through VGXNESS services. Do not create or write openspec/.
• vgxness sdd accept-artifact records explicit human-only acceptance; saving a draft never implies acceptance, and normal spec/design/tasks draft autorun after proposal acceptance is not silent acceptance.
• vgxness sdd reopen-artifact is the explicit path from a rejected artifact back to draft before revision.
• OpenCode is the primary supported provider; Claude Code is secondary/preview guidance; other providers are preview/manual extension points.
• VGXNESS exposes 63 typed MCP tools across SDD, memory, sessions, agents, skills, runs, providers, and verification. See MCP tools.

Principal entrypoint

Run vgxness with no arguments to print static safe guidance and exit 0 without opening local memory, importing OpenTUI, or writing provider config. vgx remains a compatibility alias.

For scripts, use explicit read-only commands with an explicit project:

vgxness setup status --project <name>
vgxness sdd status --project <name> --change <change>

For project-local or custom databases, use --db project-local or --db custom --db-path <path> with setup commands. Existing low-level commands remain available:

vgxness mcp install opencode --plan
vgxness mcp install opencode --yes

Verify

vgxness doctor
vgxness mcp doctor opencode
vgxness setup status

Restart OpenCode after applying config and verify that the vgxness MCP server is visible.

Rollback and recovery

OpenCode applies create a backup before merging existing config. Restore one with:

vgxness setup rollback --backup <path>

Rollback validates the backup, creates a pre-rollback backup of the current target when present, restores the selected backup byte-for-byte, and keeps the original backup if anything fails. Rerun vgxness doctor after rollback.

Common issues:

• Bun < 1.3.14: upgrade Bun and reinstall.
• Node < 22 while developing from source: upgrade Node for repository tooling.
• Bun SQLite failure: include the Bun version, OS/CPU, whether migrations applied, and the failing verify:bun-sqlite output.
• JSONC or malformed OpenCode config: convert to valid JSON or resolve manually; VGXNESS refuses unsafe rewrites.
• Existing mcp.vgxness: inspect the existing entry before rerunning setup; VGXNESS refuses overwrite by default.

Release verification matrix

CI verifies Bun on macOS, Linux, and Windows:

bun install --frozen-lockfile
bun run check:bun-lock
bun run verify:typecheck
bun run verify:test
bun run verify:test:bun-storage
bun run verify:bun-sqlite
bun run package:bun:evidence -- --require-pass

Run bun run check:bun-lock when dependency specifiers or bun.lock changed. It is read-only and helps review lock drift without installing dependencies.

Do not publish from CI. Publication or registry dry-run checks require separate explicit approval outside this verification path.

Uninstall

npm uninstall -g vgxness

Remove any user-global OpenCode/Claude config entries and local/global VGXNESS data manually if you no longer need them. Project-local provider files are external/manual and are not created, repaired, or deleted by VGXNESS setup.

More docs

• CLI reference
• Project health audit v1.14.x — historical snapshot
• Project health audit v1.10.x
• Project health audit v1.9.1
• Architecture
• Knowledge Workspace
• Obsidian MCP integration
• MCP tools
• Safety model
• Storage
• Providers
• Roadmap
• Contributing
• Glossary