Distribution

Plugins ship through a curated marketplace and install by name from the CLI. This page covers the catalog, the install flow, and the manifest that lists every installable plugin.

Plugins are in beta. The plugin API (@vellumai/plugin-api) is not yet stable and can change between releases. Pin the peerDependencies range your plugin declares, and expect breaking changes until we cut a 1.0. The install path and marketplace schema are still in flux and can change between releases.

A plugin does not have to live in your workspace to be installed. Vellum keeps a curated catalog of external plugins, and the CLI installs any of them by name. The catalog is a single manifest the Vellum team reviews and approves, so installing a plugin only ever pulls code that has been vetted into that list.

The marketplace catalog

The catalog is computed live from plugins/marketplace.json in the assistant repo. It lets Vellum surface plugins that live in other repositories without copying their code, and its shape is a subset of the Claude Code marketplace schema, so the format is familiar if you have published there.

Curation is the allowlist. Only repositories listed in the manifest appear in the catalog. There is no open registry, and the Vellum team reviews each entry before it lands.
The manifest is the catalog. It is the sole source of installable plugins. A missing or malformed manifest yields an empty catalog rather than falling back to anything else.
One surface, two clients. The same catalog backs assistant plugins search and the in-product Plugins tab.

Installing a plugin

Install by name. The CLI resolves the entry, shallow-clones the repository at its pinned commit, and writes the plugin into your workspace where the loader discovers it on the next start.

# Find a plugin in the catalog
$ assistant plugins search memory
NAME           PATH
simple-memory  vellum-ai/simple-memory

# Install it by name (clones the pinned commit)
$ assistant plugins install simple-memory
Installed plugin "simple-memory" (12 files) at ed09a4c → ~/.vellum/workspace/plugins/simple-memory
Restart the assistant to pick up the new plugin.

# Confirm what is installed
$ assistant plugins list
NAME           VERSION  STATUS
simple-memory  0.1.0    ok

The plugins command group is gated behind a beta feature flag while the install path stabilizes. Once installed, a plugin is just a directory in your workspace, so everything on the Plugins page applies to it.

The plugins CLI

Four subcommands cover the lifecycle. Expand one to see its options and behavior.

plugins searchassistant plugins search <query>

Search the catalog for plugin names matching <query> (a case-insensitive regex) and print each match with its source path.

--json: Emit machine-readable JSON instead of a table.

plugins installassistant plugins install <name>

Resolve <name> in the catalog, shallow-clone its repo at the pinned commit, and materialize it under <workspaceDir>/plugins/<name>/. The resolved commit is recorded for provenance.

--force: Overwrite an existing install of the same name.
--ref <ref>: Advanced. Read the catalog (and any adapter stub) from a different ref of the vellum-assistant repo; defaults to main. The external plugin itself is still fetched at the commit pinned in the manifest, never this ref.

Note: Installs are not hot-loaded. Restart the assistant to pick up the new plugin.

plugins listassistant plugins list

List the plugins installed under <workspaceDir>/plugins/, with each one's version and load status.

--json: Emit machine-readable JSON instead of a table.

plugins uninstallassistant plugins uninstall <name>

Remove <workspaceDir>/plugins/<name>/. Prompts for confirmation unless stdin is non-interactive.

--force: Skip the confirmation prompt.

Note: Restart the assistant to drop the plugin.

The marketplace manifest

The manifest has a top-level name, an optional owner, and a plugins array. Each entry names the plugin and points at the exact source revision to install.

{
  "name": "vellum-assistant",
  "owner": { "name": "Vellum", "url": "https://github.com/vellum-ai/vellum-assistant" },
  "plugins": [
    {
      "name": "example-plugin",
      "source": {
        "source": "github",
        "repo": "example-org/example-plugin",
        "ref": "e83c5163316f89bfbde7d9ab23ca2e25604af290"
      },
      "description": "Short summary shown in the catalog.",
      "category": "productivity",
      "homepage": "https://github.com/example-org/example-plugin",
      "license": "MIT"
    }
  ]
}

The fields each entry can set:

Field	Type	Required	Description
`name`	`string`	Required	The install name. assistant plugins install <name> resolves to this entry, and the name must be a single kebab-case segment.
`source.source`	`"github"`	Required	Source kind. Only github sources are resolved today.
`source.repo`	`string`	Required	owner/repo of the external repository to fetch from.
`source.ref`	`string`	Required	The full commit SHA (40 or 64 hex chars) to fetch. Tags and branches are rejected.
`source.path`	`string`	Optional	Directory within the repo holding the plugin root. Omit for the repository root; .. segments are rejected.
`description`	`string`	Optional	Short summary shown in the catalog.
`category`	`string`	Optional	Grouping label surfaced in the catalog.
`homepage`	`string`	Optional	Link to the plugin's home, surfaced in the catalog.
`license`	`string`	Optional	Informational license identifier, surfaced where present.

Why entries pin a commit

source.ref must be a full commit SHA. Tags and branches are rejected, because they are mutable: an upstream owner could retag or repoint them at different code, which the assistant would then clone and dynamically import. A full SHA pins the install to an immutable revision, so the reviewed manifest fully determines what executes.

To pin a release, resolve its tag to the underlying commit. Peel annotated tags with ^{} so you record the commit, not the tag object:

# Resolve a release tag to its commit SHA
$ git ls-remote https://github.com/example-org/example-plugin 'refs/tags/v1.2.0^{}'
e83c5163316f89bfbde7d9ab23ca2e25604af290  refs/tags/v1.2.0^{}

Adapting external plugins