Plugin Bundles
Agdi can install plugins from three external ecosystems: Codex, Claude, and Cursor. These are called bundles — content and metadata packs that Agdi maps into native features like skills, hooks, and MCP tools.Bundles are not the same as native Agdi 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 Agdi plugins, Agdi 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
1
Install from a directory, archive, or marketplace
2
Verify detection
Format: bundle with a subtype of codex, claude, or cursor.3
Restart and use
What Agdi maps from bundles
Not every bundle feature runs in Agdi today. Here is what works and what is detected but not yet wired.Supported now
Detected but not executed
These are recognized and shown in diagnostics, but Agdi does not run them:- Claude
agents,hooks.jsonautomation,lspServers,outputStyles - Cursor
.cursor/agents,.cursor/hooks.json,.cursor/rules - Codex inline/app metadata beyond capability reporting
Bundle formats
Codex bundles
Codex bundles
Markers:
.codex-plugin/plugin.jsonOptional content: skills/, hooks/, .mcp.json, .app.jsonCodex bundles fit Agdi best when they use skill roots and Agdi-style
hook-pack directories (HOOK.md + handler.ts).Claude bundles
Claude bundles
Two detection modes:
- Manifest-based:
.claude-plugin/plugin.json - Manifestless: default Claude layout (
skills/,commands/,agents/,hooks/,.mcp.json,settings.json)
commands/is treated as skill contentsettings.jsonis imported into embedded Pi settings (shell override keys are sanitized).mcp.jsonexposes supported stdio tools to embedded Pihooks/hooks.jsonis detected but not executed- Custom component paths in the manifest are additive (they extend defaults, not replace them)
Cursor bundles
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.jsonare detect-only
Detection precedence
Agdi checks for native plugin format first:openclaw.plugin.jsonor validpackage.jsonwithagdi.extensions— treated as native plugin- Bundle markers (
.codex-plugin/,.claude-plugin/, or default Claude/Cursor layout) — treated as bundle
Security
Bundles have a narrower trust boundary than native plugins:- Agdi 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
Troubleshooting
Bundle is detected but capabilities do not run
Bundle is detected but capabilities do not run
Run
agdi 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
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
Claude settings do not apply
Only embedded Pi settings from
settings.json are supported. Agdi does
not treat bundle settings as raw config patches.Claude hooks do not execute
Claude hooks do not execute
hooks/hooks.json is detect-only. If you need runnable hooks, use the
Agdi hook-pack layout or ship a native plugin.Related
- Install and Configure Plugins
- Building Plugins — create a native plugin
- Plugin Manifest — native manifest schema