09 plugins

Plugins

A plugin bundles skills, slash commands, agents, hooks, MCP server configurations, and LSP server configurations into one installable unit.

---

What a plugin contains

A plugin is a directory that holds any combination of these components:

• Skills -- a skills/ directory of SKILL.md files
• Slash commands -- a commands/ directory of command files
• Agents -- an agents/ directory of agent definitions
• Hooks -- a hooks/hooks.json file of lifecycle hooks. Plugin hooks also receive BUCKET_PLUGIN_ROOT and BUCKET_PLUGIN_DATA (see the Hooks guide for every environment variable passed to hooks).
• MCP servers -- a .mcp.json file of server configurations
• LSP servers -- a .lsp.json file of language server configurations

If a plugin includes a plugin.json manifest, the manifest can override paths or add metadata; otherwise components load from the convention directories. The manifest is optional: without one, Bucket discovers the components above from their standard directories.

For example, a team-tools plugin might include a deploy skill, a code-review agent, pre-commit hooks, and a Linear MCP server. Install them together in one step.

Environment variables in plugin hooks

Plugin hooks receive two environment variables beyond the standard ones set for every hook:

Variable	Description
BUCKET_PLUGIN_ROOT	Absolute path to the plugin's installed directory.
BUCKET_PLUGIN_DATA	Absolute path to the plugin's writable data directory, for plugin state, caches, and logs.

Bucket sets these values and overrides any value you declare for the same key in the hook JSON's env map. (Bucket also sets the CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA aliases for compatibility.) See the Hooks guide for every environment variable passed to hooks.

---

Plugin locations

Bucket discovers plugins from these locations, in priority order:

Location	Scope	Trust
_meta.pluginDirs (session/new / session/load)	Session -- loaded for that session only	Trusted automatically
--plugin-dir (CLI flag, bucket agent)	Process -- loaded for that agent process only	Trusted automatically
.bucket/plugins/	Project -- shared with the team through version control	Requires trust
~/.bucket/plugins/	User -- personal plugins for every project	Trusted automatically
[plugins].paths (config)	Custom directories you add in config.toml	Depends on location

Bucket also reads the .claude/plugins/ equivalents for compatibility. When two plugins share a name, the higher-priority location wins.

The Agent SDKs load per-session plugins through BucketOptions.plugins, which arrives as _meta.pluginDirs on session/new and session/load; because the caller controls the directory, these plugins are always trusted -- their hooks and MCP servers activate without a prompt, and they never persist beyond the session. The --plugin-dir flag is the process-wide equivalent for direct CLI use (repeatable: bucket agent --no-leader --plugin-dir A --plugin-dir B stdio); it applies to dedicated agent processes only and is ignored in leader mode (the shared leader discovers its own plugins).

---

Manage plugins in the TUI

Open the modal

Action	Opens
Ctrl+L (from any pane; non–VS Code family)	Plugins tab
/plugins (any terminal; required on VS Code family)	Plugins tab

The modal has five tabs: Hooks, Plugins, Marketplace, Skills, and MCP Servers. Switch tabs with Tab (forward) or Shift+Tab (backward). The /hooks, /marketplace, /skills, and /mcps commands each open the modal on the matching tab.

Plugins tab

Press Enter to expand a plugin row and show its details:

• Name and version
• Scope -- cli, project, user, custom path, or the marketplace source name
• Skills -- names or count
• Agents -- names or count
• Hooks -- count
• MCP servers -- count (or blocked when the plugin is not trusted)
• Description and path

Use these keys in the Plugins tab:

Key	Action
r	Reload all plugins
a	Add a plugin from owner/repo, a URL, or a local path
Space	Enable or disable the selected plugin
x	Uninstall the selected plugin (asks for confirmation)
f	Filter by status (all, enabled, or disabled)
Enter	Expand or collapse plugin details
/	Search plugins by name

Uninstall asks for confirmation: press lowercase y to confirm, or any other key (including Esc) to cancel.

Marketplace tab

Browse and install plugins from your configured marketplace sources.

Use these keys in the Marketplace tab:

Key	Action
i	Install the selected plugin
d	Uninstall the selected plugin (asks for confirmation)
a	Add a marketplace source
x	Remove the selected source and all its plugins (asks for confirmation)
r	Refresh marketplace sources
u	Update the selected marketplace plugin
Enter	Expand or collapse a source or plugin
/	Search plugins by name

Component summaries on list rows and per-category component details in the expanded view appear only for marketplaces that publish a plugin-index.json catalog.

---

CLI commands

Manage plugins without starting an interactive session.

Plugin commands

bucket plugin list [--json] [--available]   # List installed plugins (--available requires --json)
bucket plugin install <source> --trust      # Git URL, GitHub shorthand (user/repo), or local path
bucket plugin uninstall <name> [--confirm] [--keep-data]   # Aliases: rm, remove
bucket plugin update [<name>]               # Omit the name to update all plugins
bucket plugin enable <name>
bucket plugin disable <name>
bucket plugin details <name>                # Show the plugin's component inventory
bucket plugin validate [<path>]             # Validate plugin.json (default: current directory)
bucket plugin tag [<path>] [--push] [--force] [--dry-run]   # Tag a release from the manifest version

Run bucket plugin install <source> without --trust and Bucket prints the source and warns that installing will activate the plugin's hooks, MCP servers, and skills, then stops without installing. Add --trust to install it.

The <source> argument accepts:

• user/repo -- GitHub shorthand
• user/repo@v1.0 -- pinned to a ref
• user/repo@<commit-sha> -- pinned to an exact commit (verified after fetch)
• user/repo#subdir -- subdirectory within the repo
• https://github.com/user/repo.git -- full URL
• git@github.com:user/repo.git -- SSH
• ./local-dir or /absolute/path -- local directory

Requiring commit pins (require_sha)

Remote plugins are not cryptographically signed: an install that tracks a branch or tag runs whatever that ref points at tomorrow. Operators can require every remote install and update to pin a full commit sha (40- or 64-hex, verified against the fetched checkout):

# config.toml
[marketplace]
require_sha = true

or BUCKET_MARKETPLACE_REQUIRE_SHA=1. Both are tighten-only: either one enables the policy and neither can switch it back off. With the policy on, unpinned remote installs, marketplace installs without a published sha, and updates of branch-tracking installs are refused.

Scope: the policy covers everything fetched from a remote git URL at install or update time. Plugins vendored inside a marketplace source itself are copied from that source's synced checkout and are not covered — pin your marketplace source's content by publishing sha entries in plugin-index.json.

Marketplace commands

bucket plugin marketplace list [--json]
bucket plugin marketplace add <url>         # Git URL, GitHub shorthand (user/repo), or local path
bucket plugin marketplace remove <url>      # Git URL or local path of a configured source
bucket plugin marketplace update [<name>]   # Omit the name to refresh all sources

Example: set up a team marketplace

bucket plugin marketplace add my-org/team-plugins
bucket plugin marketplace list
bucket plugin install my-org/team-plugins --trust
bucket plugin list
bucket plugin update

---

Slash commands

In an interactive session, these commands open the modal on a specific tab. They take no arguments — manage plugins from the modal or with the bucket plugin CLI.

Command	Opens
/plugins	Plugins tab
/hooks	Hooks tab
/marketplace	Marketplace tab
/skills	Skills tab
/mcps	MCP Servers tab

---

Configuration

Configure plugin directories and per-plugin state in ~/.bucket/config.toml:

[plugins]
paths = ["~/my-plugins/custom-tools"]        # Additional plugin directories
disabled = ["user/a1b2c3d4/noisy-plugin"]    # Plugin IDs or names to skip
enabled = ["project/9f8e7d6c/team-tools"]    # Plugin IDs or names to force on

List a plugin in disabled to discover it but skip loading its components. List a plugin in enabled to activate it — plugins are disabled by default unless a CLI override or an explicit config path enables them, so add them here to turn them on. Each entry is either a plain plugin name (as shown by bucket plugin list) or a full plugin ID in the form <scope>/<hash>/<name>.

Hide the plugins UI

To hide the hooks and plugins UI — the /hooks and /plugins commands and the scrollback annotations — set this in ~/.bucket/pager.toml:

disable_plugins = true

---

Marketplace sources

Add git or local marketplace sources to discover and install plugins.

In config.toml

Each source needs a name and either a git URL (with an optional branch) or a local path:

[[marketplace.sources]]
name = "My Team Plugins"
git = "https://github.com/my-org/plugins.git"

[[marketplace.sources]]
name = "Local Dev"
path = "~/dev/my-plugins"

In settings.json

Add sources under extraKnownMarketplaces, keyed by name. Each entry's source is one of git (with url), github (with repo), or local (with path):

{
  "extraKnownMarketplaces": {
    "my-marketplace": {
      "source": { "source": "git", "url": "git@github.com:my-org/plugins.git" }
    }
  }
}

Place this file at ~/.bucket/settings.json or ~/.claude/settings.json.

---

Trust model

Enabling a plugin loads its skills, slash commands, and agents. Trust is separate and controls whether a plugin's code runs: even for an enabled plugin, its hooks, MCP servers, and LSP servers stay inactive until you trust it. This prevents an untrusted repository from running code on your machine.

Bucket trusts plugins from ~/.bucket/plugins/ automatically. Project plugins in .bucket/plugins/ require explicit trust. To trust a plugin, install it with --trust:

bucket plugin install <source> --trust

---

Inspect plugins

Run bucket inspect to see every discovered plugin and what it provides:

bucket inspect          # Show plugins with their skills, agents, hooks, and MCP servers
bucket inspect --json   # Emit machine-readable JSON

Plugin-provided components appear in their sections (Skills, Agents, MCP Servers, and so on) with a plugin: <name> label, so you can see where each component originates.

---

General keyboard shortcuts

These keys work across every tab in the modal:

Key	Action
Tab	Next tab
Shift+Tab	Previous tab
j / down-arrow	Move selection down
k / up-arrow	Move selection up
Enter	Expand or collapse the selected item
/	Search the current tab by name
Esc	Clear the search, or close the modal

Destructive remove and uninstall actions in the modal ask for confirmation. Press lowercase y to confirm, or any other key (including Esc) to cancel.