Skip to main content

​
Plugin Bundles

FluffBuzz can install plugins from three external ecosystems: Codex, Claude, and Cursor. These are called bundles — content and metadata packs that FluffBuzz maps into native features like skills, hooks, and MCP tools.
Bundles are not the same as native FluffBuzz 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 FluffBuzz plugins, FluffBuzz 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

# Local directory
fluffbuzz plugins install ./my-bundle

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

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

Verify detection

fluffbuzz plugins list
fluffbuzz plugins inspect <id>
Bundles show as Format: bundle with a subtype of codex, claude, or cursor.
3

Restart and use

fluffbuzz gateway restart
Mapped features (skills, hooks, MCP tools) are available in the next session.

​
What FluffBuzz maps from bundles

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

​
Supported now

FeatureHow it mapsApplies to
Skill contentBundle skill roots load as normal FluffBuzz skillsAll formats
Commandscommands/ and .cursor/commands/ treated as skill rootsClaude, Cursor
Hook packsFluffBuzz-style HOOK.md + handler.ts layoutsCodex
MCP toolsBundle MCP config merged into embedded Pi settings; supported stdio servers launched as subprocessesAll formats
SettingsClaude settings.json imported as embedded Pi defaultsClaude

​
Detected but not executed

These are recognized and shown in diagnostics, but FluffBuzz does not run them:
  • Claude agents, hooks.json automation, lspServers, outputStyles
  • Cursor .cursor/agents, .cursor/hooks.json, .cursor/rules
  • Codex inline/app metadata beyond capability reporting

​
Bundle formats

Markers: .codex-plugin/plugin.jsonOptional content: skills/, hooks/, .mcp.json, .app.jsonCodex bundles fit FluffBuzz best when they use skill roots and FluffBuzz-style hook-pack directories (HOOK.md + handler.ts).
Two detection modes:
  • Manifest-based: .claude-plugin/plugin.json
  • Manifestless: default Claude layout (skills/, commands/, agents/, hooks/, .mcp.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
  • hooks/hooks.json is detected but not executed
  • Custom component paths in the manifest are additive (they extend defaults, not replace them)
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

FluffBuzz checks for native plugin format first:
  1. fluffbuzz.plugin.json or valid package.json with fluffbuzz.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, FluffBuzz 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:
  • FluffBuzz 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

Run fluffbuzz plugins inspect <id>. If a capability is listed but marked as not wired, that is a product limit — not a broken install.
Make sure the bundle is enabled and the markdown files are inside a detected commands/ or skills/ root.
Only embedded Pi settings from settings.json are supported. FluffBuzz does not treat bundle settings as raw config patches.
hooks/hooks.json is detect-only. If you need runnable hooks, use the FluffBuzz hook-pack layout or ship a native plugin.