Plugins & Marketplace

Add skills, tools and hooks¶

Plugins add agent definitions, skills, hooks, MCP servers and session tools to a running Mewbo. Install one from a marketplace or a local directory and it activates at the next session start, with no restart. Nothing marks its contributions as second class, and its hooks fire alongside native ones.

For setup and installation, see Getting Started.

What a plugin can add¶

Plugin directory layout¶

A plugin is a directory. Every entry below except the manifest is optional.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # required manifest
├── agents/
│   └── code-reviewer.md     # agent definition
├── skills/
│   └── my-skill/
│       └── SKILL.md         # skill file
├── hooks/
│   └── hooks.json           # lifecycle hooks
└── .mcp.json                # MCP server configuration

plugin.json manifest¶

{
  "name": "my-plugin",
  "description": "A short description",
  "version": "1.0.0",
  "author": "Your Name",
  "requires-capabilities": ["stlite"],
  "session_tools": [
    {
      "tool_id": "submit_widget",
      "module": "my_plugin.submit_widget",
      "class": "SubmitWidgetTool"
    }
  ]
}

Path substitution¶

Substitution is a single linear replace pass with no template engine, so a body carrying no placeholders comes out byte for byte the same.

Installing plugins¶

Via CLI¶

/plugins                          # list installed plugins and their components
/plugins marketplace              # browse available plugins
/plugins install <name>           # install from the default marketplace
/plugins uninstall <name>         # remove an installed plugin

Via the console¶

Open the Plugins view from the navigation rail. The Marketplace tab lists what is available to install.

Via API¶

Configuration¶

Plugin system settings live under plugins in configs/app.json.

Each marketplaces entry takes one of three forms. The catalog is not locked to GitHub.

{
  "plugins": {
    "enabled": true,
    "marketplaces": [
      "anthropics/claude-plugins-official",
      "git.example.com/team/internal-plugins",
      "https://gitlab.com/acme/plugins.git"
    ],
    "marketplace_default_host": "github.com",
    "enabled_plugins": ["code-reviewer", "doc-generator"]
  }
}

A catalog not yet cloned is shallow cloned the first time you browse or install. The cache directory is keyed by host and owner, so two catalogs sharing a leaf name never collide. Later runs read the cache, refreshed by a fast forward git pull.

Authenticating to private and self-hosted catalogs¶

Catalogs are fetched with plain git clone, so they inherit your ambient git configuration.

• HTTPS token. Provide a credential helper. In containers, mount ~/.git-credentials in the form https://user:token@host. The Docker image enables credential.helper store, and GITHUB_TOKEN is still bridged to github.com automatically.
• SSH. Use an ssh:// or scp style entry and mount an SSH key or an agent socket. Git picks it up.
• A private CA. Point GIT_SSL_CAINFO at your CA bundle. Git reads it from the environment, so verification stays on. You never need a global GIT_SSL_NO_VERIFY.

Capability gating¶

A plugin can gate its agents, skills and session tools on a capability the client advertises. An entry whose requires-capabilities is not a subset of what the session advertised gets no tool schema and no catalog line, so nothing can invoke it by accident.

The web console sends X-Mewbo-Capabilities: stlite,apps,ask_user,generative_ui by default, one id per surface it can render. The CLI and webhook adapters send nothing unless configured to.

Declare a capability in either place. Discovery unions the two, so one line in plugin.json overlays every agent and skill in the bundle.

{
  "name": "widget-builder",
  "requires-capabilities": ["stlite"]
}

---
name: st-widget-builder
requires-capabilities: [stlite]
---

An empty requires-capabilities is the default and leaves the entry always visible.

Session tools¶

A session tool holds state for one agent instance rather than living in the global ToolRegistry. The core exit_plan_mode tool is one. So is the widget-builder's submit_widget.

Plugins contribute session tools through the session_tools array in plugin.json.

{
  "session_tools": [
    {
      "tool_id": "submit_widget",
      "module": "mewbo_core.builtin_plugins.widget_builder.submit_widget",
      "class": "SubmitWidgetTool"
    }
  ]
}

The class must implement the SessionTool protocol, whose members are listed under Architecture Overview → Session tools. An agent spawning with one of those tool ids in its allowed_tools gets its own instance. Dispatch, schema injection and termination take the same path as any bound tool, and core carries no widget branch.

Built-in plugins¶

Some plugins ship inside the product rather than in a marketplace, and need no installed_plugins.json entry.

How a library ships plugins¶

A plugin whose tools wrap a heavier substrate ships with that substrate, never in the core wheel. The wiki and SCG suites live in mewbo_graph because their tools import the graph engine. So a lean install without mewbo_graph registers neither suite, and those features are absent rather than broken.

Writing a local plugin¶

Put the plugin directory anywhere on disk and add an entry for it to an installed_plugins.json. Two paths are scanned, ~/.claude/plugins/installed_plugins.json and one in the plugin cache directory that plugins.install_path sets. The CLI install flow is the alternative, with a relative path source in a local marketplace.json.

The smallest working plugin is a directory holding only .claude-plugin/plugin.json. Everything else is discovered automatically. The bundled widget-builder is a complete example at packages/mewbo_core/src/mewbo_core/builtin_plugins/widget_builder/.