Overview
vg install wires Vibgrate AI Context into your AI assistant — skill file, MCP registration pointing at vg serve, and an optional advisory nudge. Idempotent and repo-local (changes are committable and shareable with your team).
vg install is the one verb that writes an assistant's configuration, so everything that changes that configuration is a flag on it rather than a verb of its own:
--compressalso points the assistant's base URL at the local context compression listener, durably and reversibly — and starts the listener, so one command is a working setup.--learnrewrites the assistant's guardrails from what past sessions actually got wrong.--hookswires the Claude CodePreToolUseenrichment hook so its own Grep and Glob results arrive annotated with graph context.
vg uninstall is the single revert: it removes the skill, the MCP registration, the hooks, and the compression routing for the named assistants, restoring a routed config file byte-for-byte. To remove the CLI package itself from the machine, see the uninstall help article — that is a different action.
Usage
vg install [tools...]
vg install --all
vg install --detect
vg install --list
vg install claude --compress
vg install claude --learn --apply
vg uninstall <tools...>
vg uninstall cursor --purge
Supported assistant ids
claude, cursor, windsurf, vscode, codex, gemini, grok, opencode, kilo, aider, factory, trae, kiro, amp, kimi, codebuddy, copilot-cli, pi, devin, hermes, openclaw, agents
Run vg install --list for the live support matrix (ids can grow over time). It shows, per assistant, whether the install writes an MCP registration, a skill, and a nudge; assistants without an MCP entry get the skill and nudge, and their AI reaches the graph through the vg CLI instead.
vg install
| Flag | Description |
|---|---|
[tools...] | Assistant ids to install for |
--all | Install for every supported assistant |
--detect | Detect assistants in use (repo footprint, home config, PATH) and install for those; with --list, only report what was detected |
--list | Show the support matrix and exit |
--no-hook | Skip the advisory nudge |
--hooks | Also wire the PreToolUse enrichment hook (Claude Code, project .claude/settings.json; opt-in) |
Compression routing (--compress)
| Flag | Description |
|---|---|
--compress [url] | Also route the assistant through the local compression listener by writing its base-URL config, then start the listener in the background (or reuse the healthy one on the port). The URL defaults to VG_PROXY_URL, else the host/port knobs (127.0.0.1:8787); an explicit URL or VG_PROXY_URL names a listener vg does not manage, so nothing is started. For Claude Code at project scope a SessionStart hook (vg serve --compress --background --quiet) restarts the listener when a new session finds it gone |
--compress-scope <scope> | Where --compress writes: project (repo-local, the team-shareable default) or user (home config) |
--login | Copilot only: sign in to GitHub with the device flow before writing the routing |
Agents with a base-URL config (Claude Code and Droid settings.json, Codex config.toml, OpenCode and Crush JSON, Continue and Goose YAML) get an atomic edit with a backup beside it, a marker recording exactly which fields changed, and an owner file so two concurrent sessions never undo each other. An assistant with no base-URL config is reported as unsupported, not silently skipped. The per-session alternative that writes nothing is vg serve --compress <agent>.
Learned guardrails (--learn)
| Flag | Default | Description |
|---|---|---|
--learn | — | Preview the guardrails block, as a diff; nothing is written |
--apply | — | With --learn: write the block (and save the learned output-verbosity profile) |
--since <duration> | 7d | Only sessions active within this window (7d, 48h, 2w) |
--min-evidence <n> | 2 | Occurrences before a non-loop pattern becomes a rule |
--learn-target <file> | the assistant's own | Instructions file to write: CLAUDE.local.md, AGENTS.md, GEMINI.md, or any path |
--all-projects | — | Scan sessions from every project, not just this repo |
It reads the session logs of Claude Code, Codex, Gemini CLI, Grok, OpenCode, Cursor, Copilot and Aider for this project, detects loops (the same failing command run again and again, edit / undo cycles, retry storms), repeated errors and missing-context patterns, and renders a short block between <!-- vg:learn:begin --> and <!-- vg:learn:end --> markers. Re-running replaces the block and leaves the rest of the file untouched. The analyzer is deterministic and needs no model.
vg uninstall
| Flag | Description |
|---|---|
<tools...> | Assistant ids to remove (required) |
--purge | Also delete the skill file |
--force | Restore a routed config file even when another live session still holds it |
Examples
vg install claude
vg install --all
vg install --detect
vg install --list
vg install claude --compress
vg install codex --compress --compress-scope user
vg install copilot-cli --compress --login
vg install claude --learn
vg install codex --learn --since 14d --learn-target AGENTS.md --apply
vg uninstall cursor
vg uninstall claude --purge
Related
- vg serve — the MCP server being wired in, and the compression listener
- Context compression — what
--compressroutes an assistant through - vg doctor — diagnose config, map, credentials, MCP launch, and agent routing
- vg share — share the code map with your team