Plugin bundles

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

Why bundles exist

Many useful plugins are published in Codex, Claude, or Cursor format. Instead of requiring authors to rewrite them as native OmeniaClaw plugins, OmeniaClaw 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

# Local directoryOmeniaClaw plugins install ./my-bundle # ArchiveOmeniaClaw plugins install ./my-bundle.tgz # Claude marketplaceOmeniaClaw plugins marketplace list <marketplace-name>OmeniaClaw plugins install <plugin-name>@<marketplace-name>

OmeniaClaw plugins listOmeniaClaw plugins inspect <id>

OmeniaClaw gateway restart

What OmeniaClaw maps from bundles

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

Supported now

Skill content

• bundle skill roots load as normal OmeniaClaw 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 OmeniaClaw skill loader. Cursor command markdown works through the same path.

Hook packs

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

MCP for embedded OmeniaClaw

• enabled bundles can contribute MCP server config
• OmeniaClaw merges bundle MCP config into the effective embedded OmeniaClaw settings as mcpServers
• OmeniaClaw exposes supported bundle MCP tools during embedded OmeniaClaw agent turns by launching stdio servers or connecting to HTTP servers
• the coding and messaging tool profiles include bundle MCP tools by default; use tools.deny: ["bundle-mcp"] to opt out for an agent or gateway
• project-local embedded agent 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, OmeniaClaw uses sse
• type: "http" is a CLI-native downstream shape; use transport: "streamable-http" in OmeniaClaw config. OmeniaClaw mcp set and OmeniaClaw doctor --fix normalize the common alias.
• 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

OmeniaClaw 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 -
• fragments that would start with a non-letter get a letter prefix, so numeric server keys such as 12306 become provider-safe tool prefixes
• 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 embedded-agent turns cache-stable
• profile filtering treats all tools from one bundle MCP server as plugin-owned by bundle-mcp, so profile allowlists and deny lists can include either individual exposed tool names or the bundle-mcp plugin key

Embedded OmeniaClaw settings

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

Sanitized keys:

• shellPath
• shellCommandPrefix

Embedded OmeniaClaw LSP

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

Detected but not executed

These are recognized and shown in diagnostics, but OmeniaClaw 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

Detection precedence

OmeniaClaw checks for native plugin format first:

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

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

Runtime dependencies and cleanup

• Third-party compatible bundles do not get startup npm install repair. They should be installed through OmeniaClaw plugins install and ship everything they need in the installed plugin directory.
• OmeniaClaw-owned bundled plugins are either shipped lightweight in core or downloadable through the plugin installer. Gateway startup never runs a package manager for them.
• OmeniaClaw doctor --fix removes legacy staged dependency directories and can recover downloadable plugins that are missing from the local plugin index when config references them.

Security

Bundles have a narrower trust boundary than native plugins:

• OmeniaClaw 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

Related

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