Skip to content
Docs menu

Install and manage plugins

Add plugins from a directory, npm, git or your org's marketplace, turn them on and off, configure them and see why one did not load.

View .md

venom plugin manages plugins from the shell; /plugins lists them inside a session. Nothing is fetched at startup: only venom plugin add, install, search and update touch the network.

Quick start

venom plugin add npm:@acme/venom-lint@1.2.0   # install with pi's package manager, record it
venom plugin add path:../my-plugin            # a directory: checked and recorded
venom plugin list                             # every plugin, its scope and state
venom plugin disable acme-lint                # listed, not loaded
venom plugin update                           # newer npm/git versions and org installs

venom plugin add writes the source to plugins.sources in ~/.venom/config.yaml; with --project it writes the project's venom.yaml and installs npm/git packages into the project (which must be trusted).

Sources

Source Form Where it is installed
A directory path:<dir>, or a bare ./dir, ~/dir, /dir (relative to the config file) not copied
npm npm:<package>[@version] ~/.venom/agent/npm/node_modules/<name>, or the project's .venom/npm
git git:<host>/<path>[@ref], or an https:// URL ~/.venom/agent/git/<host>/<path>, or the project's .venom/git
Org marketplace org:<name>[@<version>] with venom plugin install ~/.venom/plugins/<name>/

A source in the config that is not installed is listed as missing, with the command that installs it.

Where plugins are found

Closest first. A name found twice loads from the closest scope; the others are listed as shadowed.

Scope Where Loads
dev venom plugin dev <path> (this run only) always
cwd, repo <cwd>/.venom/plugins/<name>/, <git root>/.venom/plugins/<name>/ once the project is trusted
config plugins.sources in each venom.yaml (project files, then ~/.venom/config.yaml; lists add up) a project file's only once the project is trusted
user ~/.venom/plugins/<name>/, and the paths in ~/.venom/plugins.json (written by older versions) always, unless the org policy keeps it out
claude Claude Code's installed plugins (~/.claude/plugins/installed_plugins.json, honouring enabledPlugins) always, read-only
builtin plugins the CLI ships always

Commands

Command What it does
venom plugin list [--json], /plugins every plugin with its scope, state, what it adds and why it did not load
venom plugin add <source> [--project] install npm/git with pi's package manager (a path is only checked), add it to plugins.sources, and print what the plugin declares
venom plugin remove <name|source> [--project] take it out of plugins.sources (npm/git are uninstalled); an org install is deleted. A directory plugin: delete the directory or disable it
venom plugin enable|disable <name> [--project] set plugins.<name>.enabled (comments in the file are kept)
venom plugin update [<name|source>] update npm/git sources (a pinned version stays pinned) and org installs whose served version changed; all of them without an argument
venom plugin install org:<name>[@<version>] [--yes] [--allow-deprecated] [--json] install from your org's marketplace (below)
venom plugin search [<query>] [--json] your org's approved listings: name, version, kind, installs, rating, deprecated
venom plugin new, scaffold, check, dev for authors: see Write a plugin

States

State Meaning
loaded running in this session
disabled plugins.<name>.enabled: false
untrusted a project plugin in a project you have not trusted; nothing of it runs
invalid the manifest has a problem (unknown key, bad name, a path outside the plugin, a missing file, a newer apiVersion or minVenom than this venom); the first problem is shown
missing a configured source that is not installed
shadowed a plugin of the same name loads from a closer scope
denied the org policy keeps it out

Configuration

# venom.yaml, .venom/config.yaml or ~/.venom/config.yaml
plugins:
  sources:
    - npm:@acme/venom-charts@1.2.0
    - path:../my-plugin
  hello:
    enabled: true          # default; false lists it without loading it
    config:
      greeting: Howdy      # checked against hello's configSchema
Key Type Default What
plugins object none the plugin section; any key other than sources is a plugin name
plugins.sources list of strings [] plugin sources to load; each file's list adds to the others
plugins.*.enabled boolean true false lists the plugin as disabled and does not load it
plugins.*.config object the schema's defaults the plugin's own settings, checked against its configSchema; the closest file wins

venom config validate checks every plugins.<name>.config against its plugin's schema and names settings for plugins that are not installed. A value shaped like a key or token is dropped, as everywhere in venom's config: name an environment variable instead (for example token_env: ACME_TOKEN).

Org marketplace

With Venom Cloud, your org keeps a catalog of plugins, skills and MCP server packages that members submitted and admins approved (the console's Marketplace page).

venom cloud login                          # once
venom plugin search lint
venom plugin install org:acme-lint         # the pinned or newest approved version
venom plugin install org:acme-lint@1.2.0 --yes
venom plugin remove acme-lint

Before anything is written where venom loads plugins from, install:

  1. fetches the signed listing and verifies it with the policy key venom cloud login pinned: the signature, a 15-minute expiry, your org, the name and version asked for;
  2. refuses what the org policy denies, and a deprecated listing unless --allow-deprecated;
  3. checks the code against the listing: an uploaded bundle's SHA-256, an npm package's SHA-512 integrity (fetched with npm pack --ignore-scripts, so no install scripts run), or a git commit;
  4. works out what the plugin asks for (extension code, tools, hosts, environment variables, the commands its hooks and MCP servers start) and refuses it if that is more than the approved listing says;
  5. shows that and asks (--yes skips the question and is required without a terminal), then moves it into ~/.venom/plugins/<name>/ with a .venom-org.json record.

A directory of the same name that you made yourself is never overwritten. The only reports sent are installed and removed, for the install count.

Org policy. The signed policy's plugins section, {"install": "org", "deny": ["name"]}: deny keeps those plugins from installing or loading (built-ins included); install: "org" makes venom plugin add refuse npm, git and paths, and only org-installed and built-in plugins load. The policy's tool rules still bind every plugin's tools.

An approved, verified plugin still runs in-process with your rights. The checks confirm it is the code your admins approved, not that it is harmless.

Troubleshooting

Symptom Cause and fix
untrusted run venom trust in the project, or accept the dialog
invalid: needs venom X or newer the plugin uses API added later than your venom; upgrade venom
missing run the install command venom plugin list prints
denied your org policy keeps the plugin out; ask an admin, or install it from the org catalog
a change is not picked up after /reload state kept in module scope can survive a reload; restart venom