---
title: Install and manage plugins
description: 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.
section: plugins
order: 10
audience: [user, operator]
sources: [cli/src/plugin-command.ts, docs/plugins.md, packages/harness/src/plugins, docs/venom-config.schema.json]
features: [plugins.plugin]
---

`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

```bash
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 {#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](#org-marketplace)) |
| `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](/docs/plugins/writing.md) |

### 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 {#config}

```yaml
# 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 {#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).

```bash
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 |

## Related

- [Write a plugin](/docs/plugins/writing.md)
- [Claude Code plugins](/docs/plugins/claude-code-plugins.md)
