fluffbuzz plugins
Manage Gateway plugins, hook packs, and compatible bundles.
Related:
- Plugin system: Plugins
- Bundle compatibility: Plugin bundles
- Plugin manifest + schema: Plugin manifest
- Security hardening: Security
Commands
plugins enable.
Native FluffBuzz plugins must ship fluffbuzz.plugin.json with an inline JSON
Schema (configSchema, even if empty). Compatible bundles use their own bundle
manifests instead.
plugins list shows Format: fluffbuzz or Format: bundle. Verbose list/info
output also shows the bundle subtype (codex, claude, or cursor) plus detected bundle
capabilities.
Install
plugins section is backed by a single-file $include, plugins install/update/enable/disable/uninstall write through to that included file and leave fluffbuzz.json untouched. Root includes, include arrays, and includes with sibling overrides fail closed instead of flattening. See Config includes for the supported shapes.
If config is invalid, plugins install normally fails closed and tells you to
run fluffbuzz doctor --fix first. The only documented exception is a narrow
bundled-plugin recovery path for plugins that explicitly opt into
fluffbuzz.install.allowInvalidConfigRecovery.
--force reuses the existing install target and overwrites an already-installed
plugin or hook pack in place. Use it when you are intentionally reinstalling
the same id from a new local path, archive, ClawHub package, or npm artifact.
For routine upgrades of an already tracked npm plugin, prefer
fluffbuzz plugins update <id-or-npm-spec>.
If you run plugins install for a plugin id that is already installed, FluffBuzz
stops and points you at plugins update <id-or-npm-spec> for a normal upgrade,
or at plugins install <package> --force when you genuinely want to overwrite
the current install from a different source.
--pin applies to npm installs only. It is not supported with --marketplace,
because marketplace installs persist marketplace source metadata instead of an
npm spec.
--dangerously-force-unsafe-install is a break-glass option for false positives
in the built-in dangerous-code scanner. It allows the install to continue even
when the built-in scanner reports critical findings, but it does not
bypass plugin before_install hook policy blocks and does not bypass scan
failures.
This CLI flag applies to plugin install/update flows. Gateway-backed skill
dependency installs use the matching dangerouslyForceUnsafeInstall request
override, while fluffbuzz skills install remains a separate ClawHub skill
download/install flow.
plugins install is also the install surface for hook packs that expose
fluffbuzz.hooks in package.json. Use fluffbuzz hooks for filtered hook
visibility and per-hook enablement, not package installation.
Npm specs are registry-only (package name + optional exact version or
dist-tag). Git/URL/file specs and semver ranges are rejected. Dependency
installs run with --ignore-scripts for safety.
Bare specs and @latest stay on the stable track. If npm resolves either of
those to a prerelease, FluffBuzz stops and asks you to opt in explicitly with a
prerelease tag such as @beta/@rc or an exact prerelease version such as
@1.2.3-beta.4.
If a bare install spec matches a bundled plugin id (for example diffs), FluffBuzz
installs the bundled plugin directly. To install an npm package with the same
name, use an explicit scoped spec (for example @scope/diffs).
Supported archives: .zip, .tgz, .tar.gz, .tar.
Claude marketplace installs are also supported.
ClawHub installs use an explicit buzzhub:<package> locator:
plugin@marketplace shorthand when the marketplace name exists in Claude’s
local registry cache at ~/.claude/plugins/known_marketplaces.json:
--marketplace when you want to pass the marketplace source explicitly:
- a Claude known-marketplace name from
~/.claude/plugins/known_marketplaces.json - a local marketplace root or
marketplace.jsonpath - a GitHub repo shorthand such as
owner/repo - a GitHub repo URL such as
https://github.com/owner/repo - a git URL
- native FluffBuzz plugins (
fluffbuzz.plugin.json) - Codex-compatible bundles (
.codex-plugin/plugin.json) - Claude-compatible bundles (
.claude-plugin/plugin.jsonor the default Claude component layout) - Cursor-compatible bundles (
.cursor-plugin/plugin.json)
settings.json defaults, Claude .lsp.json /
manifest-declared lspServers defaults, Cursor command-skills, and compatible
Codex hook directories are supported; other detected bundle capabilities are
shown in diagnostics/info but are not yet wired into runtime execution.
List
--enabled to show only loaded plugins. Use --verbose to switch from the
table view to per-plugin detail lines with source/origin/version/activation
metadata. Use --json for machine-readable inventory plus registry
diagnostics.
Use --link to avoid copying a local directory (adds to plugins.load.paths):
--force is not supported with --link because linked installs reuse the
source path instead of copying over a managed install target.
Use --pin on npm installs to save the resolved exact spec (name@version) in
plugins.installs while keeping the default behavior unpinned.
Uninstall
uninstall removes plugin records from plugins.entries, plugins.installs,
the plugin allowlist, and linked plugins.load.paths entries when applicable.
For active memory plugins, the memory slot resets to memory-core.
By default, uninstall also removes the plugin install directory under the active
state-dir plugin root. Use
--keep-files to keep files on disk.
--keep-config is supported as a deprecated alias for --keep-files.
Update
plugins.installs and tracked hook-pack
installs in hooks.internal.installs.
When you pass a plugin id, FluffBuzz reuses the recorded install spec for that
plugin. That means previously stored dist-tags such as @beta and exact pinned
versions continue to be used on later update <id> runs.
For npm installs, you can also pass an explicit npm package spec with a dist-tag
or exact version. FluffBuzz resolves that package name back to the tracked plugin
record, updates that installed plugin, and records the new npm spec for future
id-based updates.
Passing the npm package name without a version or tag also resolves back to the
tracked plugin record. Use this when a plugin was pinned to an exact version and
you want to move it back to the registry’s default release line.
Before a live npm update, FluffBuzz checks the installed package version against
the npm registry metadata. If the installed version and recorded artifact
identity already match the resolved target, the update is skipped without
downloading, reinstalling, or rewriting fluffbuzz.json.
When a stored integrity hash exists and the fetched artifact hash changes,
FluffBuzz treats that as npm artifact drift. The interactive
fluffbuzz plugins update command prints the expected and actual hashes and asks
for confirmation before proceeding. Non-interactive update helpers fail closed
unless the caller supplies an explicit continuation policy.
--dangerously-force-unsafe-install is also available on plugins update as a
break-glass override for built-in dangerous-code scan false positives during
plugin updates. It still does not bypass plugin before_install policy blocks
or scan-failure blocking, and it only applies to plugin updates, not hook-pack
updates.
Inspect
- plain-capability — one capability type (e.g. a provider-only plugin)
- hybrid-capability — multiple capability types (e.g. text + speech + images)
- hook-only — only hooks, no capabilities or surfaces
- non-capability — tools/commands/services but no capabilities
--json flag outputs a machine-readable report suitable for scripting and
auditing.
inspect --all renders a fleet-wide table with shape, capability kinds,
compatibility notices, bundle capabilities, and hook summary columns.
info is an alias for inspect.
Doctor
doctor reports plugin load errors, manifest/discovery diagnostics, and
compatibility notices. When everything is clean it prints No plugin issues detected.
For module-shape failures such as missing register/activate exports, rerun
with FLUFFBUZZ_PLUGIN_LOAD_DEBUG=1 to include a compact export-shape summary in
the diagnostic output.
Marketplace
marketplace.json path, a
GitHub shorthand like owner/repo, a GitHub repo URL, or a git URL. --json
prints the resolved source label plus the parsed marketplace manifest and
plugin entries.