vg code

Overview

vg code "<instruction>" is VG Code: it proposes a minimal code edit for an instruction in plain language, grounded in Vibgrate's deterministic code map and routed to a model you choose — local or hosted. It is a capability of the Vibgrate CLI, not a separate product.

vg code is dry-run by default: it prints the proposed diff and writes nothing. Writing is opt-in and always consented — there is no quick-apply back-door.

Usage

vg code [instruction...] [options]

Run vg code with no instruction for guided interactive mode (needs a terminal). Pass an instruction to run non-interactively.

Grounded in the code map

vg code reads the deterministic code graph built by vg build, so the model sees the real symbols, files, and relationships in your project rather than guessing from a filename. Build the map first; vg code uses it to keep the edit surface small and the diff minimal.

Bring your own model — no surprise egress or install

No model is bundled, and nothing is installed by default. vg code picks a backend only from signals already present:

• a configured hosted key (for example OPENROUTER_API_KEY), or
• a model you have already pulled locally (Ollama, LM Studio).

It never dials a cloud endpoint you didn't configure. Under --local only on-device backends are eligible — if none are available it fails with an actionable message rather than reaching the network. The only path that installs a package, --provider llama-cpp, does so once, on first use, and only with --yes.

Set the model with --model or VG_CODE_MODEL; no model id is hard-coded, so pick the current best for your backend.

Dry-run, then apply with consent

# Propose only — prints the diff, writes nothing (the default)
vg code "rename getUser to fetchUser across the api package"

# Restrict the edit surface to specific files (repeatable)
vg code "add input validation" -f src/routes/users.ts

# Write the change — still needs --yes or an interactive y/N confirm
vg code "add a --timeout flag to the scan command" --apply --yes

An --apply without consent degrades to a dry-run — it is never destructive by default. Every write walks the same inspect → assess → approve → execute → verify → log lifecycle the rest of the platform enforces.

The agent, and one-shot mode

With a real model, vg code runs a multi-step agent (tool calling) that approves each edit and command as it goes. It needs a terminal to approve interactively, or --auto to run autonomously:

# Autonomous: auto-approve every edit and command (use with care)
vg code "migrate the config loader to zod" --auto --max-steps 30

# One-shot planner: a single proposed edit instead of the agent
vg code "fix the off-by-one in paginate()" --single

# After the agent finishes, run tests and make it fix failures
vg code "upgrade the express routes to v5" --auto --verify

--verify [command] runs your project's test command (from .vibgrate/code.json, or the command you pass) after the agent finishes and feeds failures back for a fix. --continue resumes the most recent session.

External tools (MCP)

vg code adopts the ecosystem-standard MCP config files — .mcp.json, .cursor/mcp.json, .vscode/mcp.json — and merges them with servers in your own config (yours wins on a name conflict). The agent may call those external tools, approval-gated like any other action.

Configure once: .vibgrate/code.json

Set your model and preferences once so you can just run vg code. Flags win over the file; the file wins over the built-in defaults. A missing or malformed file is simply "no config", never an error.

{
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-5",
  "testCommand": "npm test",
  "maxSteps": 24,
  "denyCommands": ["rm -rf", "git push"],
  "mcpServers": {}
}

Host UIs: --stream-json

--stream-json is a machine protocol for host UIs such as the VS Code panel: NDJSON agent events on stdout, approval decisions read as JSON lines on stdin. Governance is preserved — the host answers the same approval gate a human would.

Options

Exit codes

Related

• vg build — build the code map vg code is grounded in
• vg models — discover the local model backends vg code can route to
• vg ask — ask questions about the same code map
• vg fix — ranked, risk-tiered dependency upgrade plans