vgv_ai_cli

vgv_ai configures the Very Good AI tooling for the coding agents on your machine. It installs the skills, agents, MCP servers, and hooks from the VGV Claude Code plugins into every agent it supports, checks that they stay current, and removes them again without touching your own configuration.

Installation

Homebrew

On macOS and Linux, install the prebuilt executable from the Very Good Open Source tap:

brew install verygoodopensource/tap/vgv_ai

Naming the formula in full taps the repository and trusts only that formula. Upgrade with brew upgrade vgv_ai.

Install script

The script downloads the prebuilt executable for your platform from the latest GitHub release, checks it against its published SHA-256, and installs it to ~/.local/bin. It needs no Dart SDK.

curl -fsSL https://raw.githubusercontent.com/VeryGoodOpenSource/vgv_ai_cli/main/tool/install.sh | bash

Set VGV_AI_VERSION to install a specific version, such as 0.1.0, and VGV_AI_INSTALL_DIR to install somewhere else. Rerun the script to upgrade.

pub

vgv_ai is also a Dart package. You need the Dart SDK 3.13 or later.

dart pub global activate vgv_ai_cli

Either way puts the vgv_ai executable on your path. Run vgv_ai --help to confirm that it's installed. Plugin resolution clones the VGV plugins, so git has to be on your path too.

macOS and Linux are supported. On Windows, use WSL. The Codex, Copilot and Antigravity hooks are #!/bin/bash scripts that call jq, so jq has to be on your path. Native Windows, including Git Bash, is untested: vgv_ai builds paths with the host separator while those scripts expect POSIX ones.

Supported harnesses

vgv_ai calls each coding agent a harness. The flag name is what you pass to --only and --[no-]<harness>, and the config directory is where vgv_ai writes that harness's files, relative to your home directory.

Flag	Harness	Executable	Config directory
claude	Claude Code	claude	~/.claude
gemini	Gemini CLI	gemini	~/.gemini
codex	Codex	codex	~/.codex
opencode	OpenCode	opencode	~/.config/opencode
pi	Pi	pi	~/.pi/agent
copilot	GitHub Copilot CLI	copilot	~/.copilot
antigravity	Antigravity CLI	agy	~/.gemini/config

Claude Code installs the VGV plugins natively, so vgv_ai only points it at the VGV marketplace. Gemini CLI, Codex, OpenCode, Pi, and GitHub Copilot CLI share one copy of the skills in ~/.agents/skills. Antigravity CLI keeps its own copy inside its plugin.

Commands

vgv_ai has four commands.

install

install writes the Very Good AI tooling into the config of each harness you select. By default, it configures every supported harness that it finds installed on your machine.

# Configure every detected harness
vgv_ai install

# Preview what would be written, without writing anything
vgv_ai install --check

# Configure only some harnesses, whether or not they're detected, or skip one
vgv_ai install --only codex --only gemini
vgv_ai install --no-claude

# Also overwrite your values that conflict with the ones install writes
vgv_ai install --force

# Install just the VGV plugins you name, instead of choosing them
vgv_ai install --plugin vgv-wingspan

install reads the pinned plugins from the Claude Code plugin cache when it holds the pinned version, and otherwise clones them into ~/.vgv_ai/plugins. It records every file and key it writes in ~/.vgv_ai/manifest.json, which is how doctor and uninstall tell what's yours from what's VGV's.

• Your settings: settings files such as ~/.gemini/settings.json are merged, not replaced. Without --force, a value you set is kept, and install warns you about it. TOML files keep their comments and layout, unless --force needs to rewrite one.
• Instructions: files such as ~/.codex/AGENTS.md get a section between VGV's markers, and the rest of the file stays yours.
• VGV's files: agents, commands, skills, and hook scripts belong to VGV and are written whole. A file you edited since install wrote it, or one at the same path that install didn't write, is kept unless you pass --force.
• Selection: --only and --no-<harness> can't be combined.
• Plugins: pass --plugin once per plugin to name the ones you want. Without it, install run in a terminal asks which plugins to install, starting from the ones it installed before, or every pinned one the first time; run any other way, such as in CI, it installs every pinned plugin. What a previous install wrote for the plugins you leave out stays where it is; uninstall removes that.
• Plugin files: skills and agents that point at files elsewhere in their plugin, such as references and scripts, point at the plugin where install found it, in ~/.vgv_ai/plugins or the Claude Code plugin cache. Nothing is copied. If Claude Code drops its copy, those paths break until you run install again, and doctor reports the files as outdated. If ~/.vgv_ai/plugins is cleared, doctor and install fetch it again to the same place.

doctor

doctor checks that the Very Good AI tooling install wrote is still there, unchanged, and current with this version of vgv_ai. It never changes your harness config or the manifest.

# Check every harness
vgv_ai doctor

# Check only some harnesses, or skip one
vgv_ai doctor --only codex --only gemini
vgv_ai doctor --no-claude

For each harness, doctor reports the files and keys that are missing, were changed since, or differ from what this version installs. It also compares the plugin versions each harness was installed from with the ones this version pins, notes a pinned plugin a harness wasn't installed from, suggests configuring a harness that's installed but not configured, and warns about a configured harness that's no longer installed.

Every problem comes with the install command that fixes it, and the report ends with one command that fixes everything install can, such as vgv_ai install --only gemini --only codex. That command includes --force only when changed files need restoring, and then --force applies to every harness it names.

To check whether files are current, doctor resolves the plugins the same way install does, so it may clone them into ~/.vgv_ai/plugins.

uninstall

uninstall removes only what ~/.vgv_ai/manifest.json records that install wrote, so your own files, keys, comments, and sections stay.

# Remove the tooling from every harness
vgv_ai uninstall

# Preview what would be removed, without removing anything
vgv_ai uninstall --check

# Remove the tooling from only some harnesses, or keep one
vgv_ai uninstall --only codex --only gemini
vgv_ai uninstall --no-claude

# Also remove what you changed since install
vgv_ai uninstall --force

• Selection: the harnesses come from the manifest, not from what's installed, so you can clean up an agent you've already removed. --only and --no-<harness> can't be combined.
• Shared skills: the skills in ~/.agents/skills are shared by every agent, so they're removed only when every harness the manifest records is. A partial run keeps them and tells you how to remove them.
• Your changes: without --force, a file, key, or section you changed since install is kept, and a warning names it.
• Directories: empty directories left behind are removed, but ~/.agents/skills and each harness's config directory, such as ~/.codex, stay.
• Manifest: it keeps whatever is left to remove, and it's deleted once nothing is. --check changes nothing, not even the manifest.

update

update checks pub.dev for a newer version of vgv_ai. It takes no flags.

vgv_ai update

When you installed with pub, it updates vgv_ai itself. Otherwise it prints the command that updates your installation: brew upgrade vgv_ai for Homebrew, or the install script for a prebuilt binary.

Every other command also checks for a newer version when it finishes, and prints the same command when there is one.

Global options

These options work without a command:

# Show the version
vgv_ai --version

# Show usage help, for vgv_ai or for one command
vgv_ai --help
vgv_ai install --help

# Log every step, including the shell commands vgv_ai runs
vgv_ai install --verbose

Shell completion

vgv_ai install-completion-files

Installs shell completion for bash and zsh. Remove it again with vgv_ai uninstall-completion-files.

Contributing

To work on vgv_ai, see the contributing guide.