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.
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 installsvenom 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-lintBefore anything is written where venom loads plugins from, install:
- fetches the signed listing and verifies it with the policy key
venom cloud loginpinned: the signature, a 15-minute expiry, your org, the name and version asked for; - refuses what the org policy denies, and a deprecated listing unless
--allow-deprecated; - 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; - 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;
- shows that and asks (
--yesskips the question and is required without a terminal), then moves it into~/.venom/plugins/<name>/with a.venom-org.jsonrecord.
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 |