Marketplace plugin system

English | 中文

The marketplace system lets you discover, install, and manage plugins from Git, local, or direct-catalog sources. It is compatible with the Claude Code plugin registry format.

Quick start

/marketplace add anthropics/claude-plugins-official
/marketplace install wordpress.com@claude-plugins-official

In the TUI, /marketplace with no arguments opens the interactive plugin browser. In non-TUI command handling, /marketplace lists configured marketplaces; use /marketplace discover to browse.

Concepts

A marketplace is a Git repository (or local directory) containing a catalog file at .omp-plugin/marketplace.json (preferred) or .claude-plugin/marketplace.json (Claude Code-compatible fallback). The catalog lists available plugins with their sources, descriptions, and metadata.

A plugin is a directory containing Claude/OMP plugin content such as skills, commands, agents, hooks, tools, MCP servers, or LSP servers. Marketplace installs also load extension modules declared by package.json omp.extensions: installation symlinks the cached plugin into the scope’s node_modules tree and records it in musepi-plugins.lock.json, the same runtime surfaces used by npm-installed and musepi plugin linked plugins. Plugins are identified by name@marketplace (e.g. code-review@claude-plugins-official).

Scopes: marketplace plugins can be installed at two scopes:

• user (default) – available in all projects, stored in ~/.musepi/plugins/installed_plugins.json
• project – available only in the active project, stored in the nearest project .musepi/plugins/installed_plugins.json

Enabled project-scoped installs shadow enabled user-scoped installs of the same plugin. A disabled project install does not shadow the user install.

Commands

Interactive mode

Marketplace management

Plugin operations

CLI equivalents

The same operations are available from the command line:

musepi plugin marketplace add <source>
musepi plugin marketplace remove <name>
musepi plugin marketplace update [name]
musepi plugin marketplace list
musepi plugin discover [marketplace]
musepi plugin install [--force] [--scope user|project] name@marketplace
musepi plugin uninstall [--scope user|project] name@marketplace
musepi plugin upgrade [--scope user|project] [name@marketplace]
musepi plugin enable [--scope user|project] name@marketplace
musepi plugin disable [--scope user|project] name@marketplace

Marketplace sources

When you run /marketplace add <source>, the system classifies the source:

Git and local sources must contain a catalog at .omp-plugin/marketplace.json (preferred) or .claude-plugin/marketplace.json (Claude Code-compatible fallback). Direct catalog URLs cache only the JSON catalog; plugins in URL-sourced catalogs cannot use relative string sources like "./plugins/foo".

Catalog format (marketplace.json)

A marketplace catalog lives at .omp-plugin/marketplace.json in the repository root. When musepi is the only intended consumer, prefer this path. To remain Claude Code-compatible (musepi loads the same shape from either path), publish at .claude-plugin/marketplace.json instead — musepi uses it as a fallback when .omp-plugin/marketplace.json is absent. A repository may ship both: musepi reads the .omp-plugin/ copy, Claude Code reads the .claude-plugin/ copy. Same catalog format either way:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "metadata": {
    "description": "A collection of plugins",
    "version": "1.0.0",
    "pluginRoot": "plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "What this plugin does",
      "source": "./my-plugin",
      "category": "development",
      "homepage": "https://github.com/you/my-plugin"
    }
  ]
}

Required fields

Top-level metadata.description, metadata.version, and metadata.pluginRoot are optional. When metadata.pluginRoot is set, it is prepended to relative plugin source paths.

Plugin entry fields

Plugin source formats

The source field supports these formats. String sources must start with ./ and are resolved inside the marketplace root, after optional metadata.pluginRoot is prepended:

Relative path (within the marketplace repo):

"source": "./my-plugin"

Git repository URL:

"source": {
  "source": "url",
  "url": "https://github.com/org/repo.git",
  "sha": "abc123..."
}

GitHub shorthand:

"source": {
  "source": "github",
  "repo": "org/repo",
  "ref": "main",
  "sha": "abc123..."
}

Git subdirectory (monorepo):

"source": {
  "source": "git-subdir",
  "url": "https://github.com/org/monorepo.git",
  "path": "plugins/my-plugin",
  "ref": "main",
  "sha": "abc123..."
}

npm package (parsed but not installable yet):

"source": {
  "source": "npm",
  "package": "@scope/my-plugin",
  "version": "1.0.0"
}

Current installer behavior rejects npm marketplace sources with npm plugin sources are not yet supported; use relative, GitHub, URL, or git-subdir sources.

On-disk layout

~/.musepi/
  marketplaces.json              # Registry of added marketplaces
  plugins/
    installed_plugins.json       # User-scoped marketplace plugins (version: 2)
    musepi-plugins.lock.json         # Runtime enable/feature state
    node_modules/<package>        # Symlink to the cached plugin
    cache/
      marketplaces/<name>/       # Cached marketplace clone/catalog
      plugins/<marketplace>___<plugin>___<version>/  # Cached plugin directories

<project>/.musepi/
  plugins/
    installed_plugins.json       # Project-scoped marketplace plugins (version: 2)
    musepi-plugins.lock.json         # Project runtime enable/feature state
    node_modules/<package>        # Symlink to the cached plugin

Naming rules

Marketplace and plugin names must:

• Start and end with a lowercase letter or digit
• Contain only lowercase letters, digits, hyphens, and dots
• Be at most 64 characters

Plugin IDs (name@marketplace) must be at most 128 characters total.

Valid examples: my-plugin, code-review, wordpress.com, ai-firstify Invalid examples: -bad, bad-, .bad, Bad, under_score