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, Foundry Local), or
• a Code Mode pack from vg models install (Spark / Flow / Forge).

Prefer --mode spark|flow|forge over a raw model name when you use Code Modes; omit both --mode and --model to auto-fit from live memory and repo signals.

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.

Tool results are compressed

Inside the agent loop there is no wire to sit on, so vg code applies context compression itself: a bulky run_command, search_code or web_fetch result is compressed once on the way into the transcript instead of being re-billed on every later step. Reads an edit is computed from, and failed results, are never touched. The original stays in the local retrievable store and the model gets a vg_retrieve tool, so it can pull back the whole result or just the lines it needs. Tokens are counted in the routed model's tokenizer; the run reports what it saved and vg savings counts it under the vg-code client. Set VG_CODE_COMPRESS=0 to turn it off.

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 Code — what the capability does across the CLI and Vibgrate for VS Code
• vg build — build the code map vg code is grounded in
• vg models — Code Modes and 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