@osovv/vvcode

vvcode

vvcode is a Bun-based CLI package for launching OpenCode with preset-driven runtime overlays.

Install

bun add -g @osovv/vvcode

For local development from this repo:

bun install
bun run cli -- --help

Config layout

Global config path:

~/.config/vvcode/config.jsonc

Project config path:

.vvcode/config.jsonc

The current behavior is:

• Global config is the source of shared presets and profiles.
• Project config is optional for launch if a project root already exists.
• vvcode init creates a minimal project config scaffold.
• vvcode preset add <name> copies a preset from global config into the project config.
• vvcode preset remove <name> removes a copied project preset and prunes unused copied profiles.

Quick start

Initialize a project-local config:

vvcode init

See which presets are available:

vvcode preset list

Copy a global preset into the current project:

vvcode preset add openai

Launch OpenCode with a preset:

vvcode opencode --preset openai

Or use the shorthand form:

vvcode --preset openai

Commands

Show help:

vvcode help
vvcode --help

Initialize project config:

vvcode init
vvcode init --project-root /path/to/project

Launch OpenCode:

vvcode opencode --preset <name>
vvcode --preset <name>

Any extra arguments after the vvcode launch flags are forwarded to opencode.

Examples:

vvcode --preset openai run "say hello"
vvcode --preset openai run "say hello" --format json
vvcode --preset openai -p "say hello"

-p and --prompt are vvcode shorthand for launching opencode run <message>.

By default vvcode starts the shell with:

opencode

You can override the shell command, for example:

OPENCODE_SHELL_COMMAND='bun x opencode-ai' vvcode --preset openai

Options:

• --preset for the preset name.
• --global-config, -c to override the global config file path.
• --project-root, -r to launch from a different project root.
• -p, --prompt to shorthand into opencode run <message> for non-interactive tests.

Manage presets:

vvcode preset list
vvcode preset add <preset-name>
vvcode preset remove <preset-name>

preset list prints one preset per line with its source label:

• global
• project
• project-overrides-global

Runtime artifacts

• .vvcode/local/runtime/overlays/
• .vvcode/local/runtime/traces/
• .vvcode/local/runtime/failures/
• .vvcode/memory/project/
• .vvcode/memory/agent/
• .vvcode/local/memory/session/
• .vvcode/local/memory/subagent/

Packaging notes

• Package name: @osovv/vvcode
• CLI bin: vvcode
• Published runtime entry: dist/vvcode.js
• Build command: bun run build
• Local dev command: bun run cli -- --help
• prepack builds dist automatically before publish or pack
• Scoped publish target: npm publish --access=public