Plugin Bundles

Velaclaw can install plugins from three external ecosystems: Codex, Claude, and Cursor. These are called bundles — content and metadata packs that Velaclaw maps into native features like skills, hooks, and MCP tools.

Bundles are not the same as native Velaclaw plugins. Native plugins run in-process and can register any capability. Bundles are content packs with selective feature mapping and a narrower trust boundary.

Why bundles exist

Many useful plugins are published in Codex, Claude, or Cursor format. Instead of requiring authors to rewrite them as native Velaclaw plugins, Velaclaw detects these formats and maps their supported content into the native feature set. This means you can install a Claude command pack or a Codex skill bundle and use it immediately.

Install a bundle

Install from a directory, archive, or marketplace

# Local directory
velaclaw plugins install ./my-bundle

# Archive
velaclaw plugins install ./my-bundle.tgz

# Claude marketplace
velaclaw plugins marketplace list <marketplace-name>
velaclaw plugins install <plugin-name>@<marketplace-name>

Verify detection

velaclaw plugins list
velaclaw plugins inspect <id>

Bundles show as Format: bundle with a subtype of codex, claude, or cursor.

Restart and use

velaclaw gateway restart

Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.

What Velaclaw maps from bundles

Not every bundle feature runs in Velaclaw today. Here is what works and what is detected but not yet wired.

Supported now

Feature	How it maps	Applies to
Skill content	Bundle skill roots load as normal Velaclaw skills	All formats
Commands	`commands/` and `.cursor/commands/` treated as skill roots	Claude, Cursor
Hook packs	Velaclaw-style `HOOK.md` + `handler.ts` layouts	Codex
MCP tools	Bundle MCP config merged into embedded Pi settings; supported stdio and HTTP servers loaded	All formats
LSP servers	Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded Pi LSP defaults	Claude
Settings	Claude `settings.json` imported as embedded Pi defaults	Claude

Skill content

bundle skill roots load as normal Velaclaw skill roots
Claude commands roots are treated as additional skill roots
Cursor .cursor/commands roots are treated as additional skill roots

This means Claude markdown command files work through the normal Velaclaw skill loader. Cursor command markdown works through the same path.

Hook packs

bundle hook roots work only when they use the normal Velaclaw hook-pack layout. Today this is primarily the Codex-compatible case:
- HOOK.md
- handler.ts or handler.js

MCP for Pi

enabled bundles can contribute MCP server config
Velaclaw merges bundle MCP config into the effective embedded Pi settings as mcpServers
Velaclaw exposes supported bundle MCP tools during embedded Pi agent turns by launching stdio servers or connecting to HTTP servers
project-local Pi settings still apply after bundle defaults, so workspace settings can override bundle MCP entries when needed
bundle MCP tool catalogs are sorted deterministically before registration, so upstream listTools() order changes do not thrash prompt-cache tool blocks

Transports

MCP servers can use stdio or HTTP transport: Stdio launches a child process:

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "node",
        "args": ["server.js"],
        "env": { "PORT": "3000" }
      }
    }
  }
}

HTTP connects to a running MCP server over sse by default, or streamable-http when requested:

{
  "mcp": {
    "servers": {
      "my-server": {
        "url": "http://localhost:3100/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
        },
        "connectionTimeoutMs": 30000
      }
    }
  }
}

transport may be set to "streamable-http" or "sse"; when omitted, Velaclaw uses sse
only http: and https: URL schemes are allowed
headers values support ${ENV_VAR} interpolation
a server entry with both command and url is rejected
URL credentials (userinfo and query params) are redacted from tool descriptions and logs
connectionTimeoutMs overrides the default 30-second connection timeout for both stdio and HTTP transports

Tool naming

Velaclaw registers bundle MCP tools with provider-safe names in the form serverName__toolName. For example, a server keyed "vigil-harbor" exposing a memory_search tool registers as vigil-harbor__memory_search.

characters outside A-Za-z0-9_- are replaced with -
server prefixes are capped at 30 characters
full tool names are capped at 64 characters
empty server names fall back to mcp
colliding sanitized names are disambiguated with numeric suffixes
final exposed tool order is deterministic by safe name to keep repeated Pi turns cache-stable

Embedded Pi settings

Claude settings.json is imported as default embedded Pi settings when the bundle is enabled
Velaclaw sanitizes shell override keys before applying them

Sanitized keys:

shellPath
shellCommandPrefix

Embedded Pi LSP

enabled Claude bundles can contribute LSP server config
Velaclaw loads .lsp.json plus any manifest-declared lspServers paths
bundle LSP config is merged into the effective embedded Pi LSP defaults
only supported stdio-backed LSP servers are runnable today; unsupported transports still show up in velaclaw plugins inspect <id>

Detected but not executed

These are recognized and shown in diagnostics, but Velaclaw does not run them:

Claude agents, hooks.json automation, outputStyles
Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
Codex inline/app metadata beyond capability reporting

Bundle formats

Codex bundles

Markers: .codex-plugin/plugin.jsonOptional content: skills/, hooks/, .mcp.json, .app.jsonCodex bundles fit Velaclaw best when they use skill roots and Velaclaw-style hook-pack directories (HOOK.md + handler.ts).

Claude bundles

Two detection modes:

Manifest-based: .claude-plugin/plugin.json
Manifestless: default Claude layout (skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json)

Claude-specific behavior:

commands/ is treated as skill content
settings.json is imported into embedded Pi settings (shell override keys are sanitized)
.mcp.json exposes supported stdio tools to embedded Pi
.lsp.json plus manifest-declared lspServers paths load into embedded Pi LSP defaults
hooks/hooks.json is detected but not executed
Custom component paths in the manifest are additive (they extend defaults, not replace them)

Cursor bundles

Markers: .cursor-plugin/plugin.jsonOptional content: skills/, .cursor/commands/, .cursor/agents/, .cursor/rules/, .cursor/hooks.json, .mcp.json

.cursor/commands/ is treated as skill content
.cursor/rules/, .cursor/agents/, and .cursor/hooks.json are detect-only

Detection precedence

Velaclaw checks for native plugin format first:

velaclaw.plugin.json or valid package.json with velaclaw.extensions — treated as native plugin
Bundle markers (.codex-plugin/, .claude-plugin/, or default Claude/Cursor layout) — treated as bundle

If a directory contains both, Velaclaw uses the native path. This prevents dual-format packages from being partially installed as bundles.

Security

Bundles have a narrower trust boundary than native plugins:

Velaclaw does not load arbitrary bundle runtime modules in-process
Skills and hook-pack paths must stay inside the plugin root (boundary-checked)
Settings files are read with the same boundary checks
Supported stdio MCP servers may be launched as subprocesses

This makes bundles safer by default, but you should still treat third-party bundles as trusted content for the features they do expose.

Troubleshooting

Bundle is detected but capabilities do not run

Run velaclaw plugins inspect <id>. If a capability is listed but marked as not wired, that is a product limit — not a broken install.

Claude command files do not appear

Make sure the bundle is enabled and the markdown files are inside a detected commands/ or skills/ root.

Claude settings do not apply

Only embedded Pi settings from settings.json are supported. Velaclaw does not treat bundle settings as raw config patches.

Claude hooks do not execute

hooks/hooks.json is detect-only. If you need runnable hooks, use the Velaclaw hook-pack layout or ship a native plugin.

Install and Configure Plugins
Building Plugins — create a native plugin
Plugin Manifest — native manifest schema

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Plugin Bundles

Plugin Bundles

Why bundles exist

Install a bundle

What Velaclaw maps from bundles

Supported now

Skill content

Hook packs

MCP for Pi

Transports

Tool naming

Embedded Pi settings

Embedded Pi LSP

Detected but not executed

Bundle formats

Detection precedence

Security

Troubleshooting

​Plugin Bundles

​Why bundles exist

​Install a bundle

​What Velaclaw maps from bundles

​Supported now

​Skill content

​Hook packs

​MCP for Pi

Transports

Tool naming

​Embedded Pi settings

​Embedded Pi LSP

​Detected but not executed

​Bundle formats

​Detection precedence

​Security

​Troubleshooting

​Related

Plugin Bundles

Why bundles exist

Install a bundle

What Velaclaw maps from bundles

Supported now

Skill content

Hook packs

MCP for Pi

Embedded Pi settings

Embedded Pi LSP

Detected but not executed

Bundle formats

Detection precedence

Security

Troubleshooting

Related