Marketplace plugin system

Discover, install, and manage plugins from Git, local, or catalog sources. Catalog layout is compatible with the Claude Code plugin registry format.

Quick start

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

The interactive /marketplace TUI was removed from Veyyon. Manage marketplaces and marketplace plugins through the veyyon plugin CLI. Inside the TUI, /plugins list shows installed npm/link plugins.

Concepts

A marketplace is a Git repository (or local directory) containing a catalog file at .veyyon-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/Veyyon plugin content such as skills, commands, agents, hooks, tools, MCP servers, or LSP servers. Extension modules (package.json veyyon.extensions entry points; legacy omp/pi keys still accepted) load from marketplace installs just as they do from npm-installed or veyyon plugin linked plugins, because the install symlinks the cached plugin into the runtime node_modules tree. 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 under the active profile, stored in ~/.veyyon/profiles/<profile>/plugins/installed_plugins.json (default profile: profiles/default/plugins/)
project – available only in the active project, stored in the nearest project .veyyon/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

Marketplace management:

veyyon plugin marketplace add <source>
veyyon plugin marketplace remove <name>
veyyon plugin marketplace update [name]
veyyon plugin marketplace list

Plugin operations:

veyyon plugin discover [marketplace]
veyyon plugin install [--force] [--scope user|project] name@marketplace
veyyon plugin uninstall [--scope user|project] name@marketplace
veyyon plugin upgrade [--scope user|project] [name@marketplace]
veyyon plugin enable [--scope user|project] name@marketplace
veyyon plugin disable [--scope user|project] name@marketplace

Marketplace sources

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

Source format	Type	Example
`owner/repo`	GitHub shorthand	`anthropics/claude-plugins-official`
`https://...*.json`	Direct catalog URL	`https://example.com/marketplace.json`
`https://...` / `http://...`	Git repository unless the URL path ends in `.json`	`https://github.com/org/repo`
`git@...` / `ssh://...`	Git repository	`[email protected]:org/repo.git`
`./path` or `~/path` or an absolute path	Local directory	`./my-marketplace`

Git and local sources must contain a catalog at .veyyon-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 .veyyon-plugin/marketplace.json in the repository root. When veyyon is the only intended consumer, prefer this path. To remain Claude Code-compatible (veyyon loads the same shape from either path), publish at .claude-plugin/marketplace.json instead, veyyon uses it as a fallback when .veyyon-plugin/marketplace.json is absent. A repository may ship both: veyyon reads the .veyyon-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": "[email protected]"
  },
  "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

Field	Description
`name`	Marketplace name. Lowercase alphanumeric, hyphens, and dots. Must start and end with alphanumeric. Max 64 chars.
`owner.name`	Marketplace owner name
`plugins`	Array of plugin entries

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

Field	Required	Description
`name`	yes	Plugin name (same rules as marketplace name)
`source`	yes	Where to find the plugin (see below)
`description`	no	Short description
`version`	no	Version string; install version falls back to plugin manifest, source SHA, then `0.0.0`
`author`	no	`{ name, email? }`
`homepage`	no	URL
`repository`	no	Repository URL/string
`license`	no	License string
`keywords`	no	Array of string keywords
`category`	no	Category string (e.g. `development`, `productivity`, `security`)
`tags`	no	Array of string tags
`strict`	no	Boolean
`commands`	no	Slash commands provided
`agents`	no	Agents provided
`hooks`	no	Hook definitions
`mcpServers`	no	MCP server definitions
`lspServers`	no	LSP server definitions or path; copied to `.lsp.json` on install

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

~/.veyyon/
  marketplaces.json              # Registry of added marketplaces
  profiles/<profile>/plugins/
    installed_plugins.json       # User-scoped marketplace plugins (version: 2)
    cache/
      marketplaces/<name>/       # Cached marketplace clone/catalog
      plugins/<marketplace>___<plugin>___<version>/  # Cached plugin directories

<project>/.veyyon/
  plugins/
    installed_plugins.json       # Project-scoped marketplace plugins (version: 2)

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

Keyboard shortcuts

The Veyyon Harness Handbook