Extensibility
Build on top of Vellum with plugins. A plugin bundles hooks, tools, and more into a single installable package that extends what your assistant can do.
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. We will note the stability of each surface as this section grows.
This section covers how you can teach your Assistant to extend itself by building new features without touching the core harness logic.
What is a plugin?
A plugin is a directory in your assistant's workspace (<workspaceDir>/plugins/<name>/) that groups different surfaces into one cohesive capability that they can now perform. Your assistant can build plugins directly in this folder in the workspace 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. Each surface can also be contributed directly to the workspace in the corresponding /workspace/<surface>/<name>/ directory.
| Surface | Lives in | What it does |
|---|---|---|
| Lifecycle hooks | hooks/<name>.ts | Run code at fixed points in the Assistant's lifecycle to read or transform what flows through. |
| Skills | skills/<name>/ | Directories of instructions and associated assets, scripts, and resources that the Assistant loads dynamically when relevant. |
| Model-visible tools | tools/<name>.ts | Add new tools the model can call. Plugin tools land in the same catalog as built-in tools. |
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, which is the only supported contract. Anything not exported from there is internal and can change without notice.
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.
The Personal AI you were promised
