plugin-builder

# Plugin Builder

Build on top of Vellum with plugins. A plugin bundles multiple surfaces into a single installable package that extends what an assistant can do.

Plugins are in beta. The peer-dep range you declare is what gets you load. Treat everything you write as something that can break between Vellum releases until 1.0 ships, and pin a real range.

## What is a plugin?

A plugin is a directory in the assistant's workspace (`<workspaceDir>/plugins/<name>/`) that groups different surfaces into one cohesive capability. The assistant can build plugins directly in this folder or install one from the community via the CLI:

```
assistant plugins install <name>
```

Plugins can also be discovered and managed from the Plugins tab in the app, or searched from the CLI with `assistant plugins search`. The catalog is a curated allowlist that the Vellum team approves and curates.

## The surfaces a plugin can bundle

A single plugin can contribute several different kinds of behavior. Each surface is discovered by convention from a named subdirectory. Missing directories are simply skipped, so a plugin contributes only what it ships.

| Surface                                    | Lives in                | What it does                                                                                                                                     |
| ------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Lifecycle hooks](references/hooks.md)     | `hooks/<name>.ts`       | Run code at fixed points in the Assistant's lifecycle to read or transform what flows through, and broadcast progress to the UI.                 |
| [Skills](references/skills.md)             | `skills/<name>/`        | Directories of instructions and associated assets, scripts, and resources that the Assistant loads dynamically when relevant.                    |
| [Model-visible tools](references/tools.md) | `tools/<name>.ts`       | Add new tools the model can call. Plugin tools land in the same catalog as built-in tools.                                                       |
| [MCP servers](references/mcp.md)           | `mcp.json`              | Declare MCP servers the assistant connects on install. Their tools land as `mcp__<id>__<tool>` alongside workspace-configured MCP tools.         |
| [HTTP routes](references/routes.md)        | `routes/<path>.ts`      | Serve HTTP endpoints in the plugin's own `/x/plugins/<name>/` namespace (apps, local callers, and the handler behind public ingress).            |
| [Channels](references/channels.md)         | `channels/ingress.json` | Declare public webhook and WebSocket routes that make the plugin a channel. The gateway signature-checks them and forwards to matching routes.   |
| [Apps](references/apps.md)                 | `apps/<name>/`          | Ship persistent interactive apps (dashboards, trackers, visualizations) compiled from a Preact + TSX bundle and rendered in the workspace panel. |

The two extensibility patterns serve different goals. **Plugins are for distribution**: you intend to share the capability, publish to the marketplace, or install it across multiple assistants. The plugin manifest (`package.json`), the `@vellumai/plugin-api` peer dependency, and the install flow exist to make a capability portable, versioned, and discoverable by others.

**Direct workspace contributions are for personal extension**: you simply want to extend your assistant and have no intention of distributing the work. Skip the plugin packaging entirely. Drop the file directly into the matching top-level workspace directory (`/workspace/tools/<name>/` for a tool, `/workspace/skills/<name>/` for a skill, etc.) and the assistant picks it up automatically. No manifest, no install step, no peer dependency. MCP servers can also be added in settings without a plugin; `mcp.json` is the way to ship them with one.

Several surfaces that plugins contribute run in the same process as the main Assistant process. They can import all internal methods from the Assistant from the single public package, [`@vellumai/plugin-api`](https://github.com/vellum-ai/vellum-assistant/tree/main/assistant/src/plugin-api), which is the only supported contract. Anything not exported from there is internal and can change without notice. See `references/plugins.md` for the full export surface.

## Coming from another harness?

Vellum's plugin model was designed to line up with the agent harnesses you may already use. The shared vocabulary is deliberate to be as portable as possible with the other entrants in the industry.

## Before you write a single file

Ask before building. Six questions, in this order. Stop if the user is unclear on any of them.

1. **What job does the plugin do?** One sentence, plain language. If you cannot write this, the plugin should not be built yet.
2. **Which surfaces does it ship?** Pick from the surfaces table above. Most plugins ship one or two, not all of them. See `references/plugins.md` for the directory layout and manifest, and the surface-specific references for each surface's contract.
3. **Does it need credentials?** An API key, OAuth token, or webhook secret is not a value that belongs in a `.ts` file. For LLM inference credentials, use `getConfiguredProvider()` from `@vellumai/plugin-api` to route through the workspace's stored credentials without handling plaintext. For other credential types (OAuth tokens, webhook secrets), store them via the credential vault and resolve at runtime with `resolveCredential()` from `@vellumai/plugin-api`, which returns the plaintext value scoped to the service named after your plugin. Catch `CredentialResolutionError` to degrade gracefully.
4. **Does it keep state?** A plugin is fully self-contained: durable state lives in its `data/` directory (`InitContext.pluginStorageDir`), w