Local marketplace
A repository can carry its own marketplace catalog. Users then add the repository as a marketplace and install the plugin from it — no service, no submission, no account. During development it is how you install the plugin the way a user eventually will.
Three commands write these catalogs. plugin init registers the
plugin it scaffolds, marketplace init derives a catalog for every plugin a repository holds, and
marketplace add lists a plugin that lives
somewhere else. All three write the same files; none publishes anything.
marketplace update changes an entry one of them
wrote, and marketplace validate checks
that what they wrote is what each runtime will load.
For the shorter loop that skips the catalog entirely — the working copy dropped straight into a
runtime’s local plugin directory — see plugin install.
Where each runtime looks
Section titled “Where each runtime looks”| Runtime | Catalog it reads | Add the marketplace | Install |
|---|---|---|---|
| Claude Code | .claude-plugin/marketplace.json |
/plugin marketplace add <owner>/<repo> |
/plugin install <plugin>@<marketplace> |
| Codex | .agents/plugins/marketplace.json, or the Claude path |
codex plugin marketplace add <source> |
codex plugin add <plugin>@<marketplace> |
| GitHub Copilot CLI | .github/plugin/marketplace.json, or the Claude path |
copilot plugin marketplace add <spec> |
copilot plugin install <plugin>@<marketplace> |
| Cursor | .cursor-plugin/marketplace.json, or the Claude path |
an admin imports the repository as a team marketplace | Customize sidebar |
Three of the four read .claude-plugin/marketplace.json, so one file covers Claude Code, Codex, and
Copilot CLI if you want fewer. Two traps: Codex installs with plugin add where Copilot CLI uses
plugin install, and Codex finds a catalog only when the file is named marketplace.json.
Cursor is the exception. It reads a repository catalog, but nothing on the command line adds one:
a developer tests through plugin install, and users get the plugin when an admin imports the
repository from the Cursor dashboard. Generate the file; write no Cursor install command.
plugin init registers one plugin
Section titled “plugin init registers one plugin”universal-plugin plugin init --vendor claude-code --vendor cursorBeside the canonical plugin.json, this writes a catalog for each selected vendor at the
repository root, each carrying an entry for this plugin:
{ "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "acme-widgets-local", "owner": { "name": "acme" }, "plugins": [{ "name": "my-plugin", "source": "./packages/my-plugin" }]}The catalog belongs to the repository, not to the plugin: it sits at the repository root and lists
every plugin the repository develops. So it is named after the repository, <owner>-<repo>-local,
with -local separating it from a published marketplace of the same plugins. source is the path
from the repository root to the plugin.
owner comes from the canonical manifest’s author, else the package.json that ships it, else the
account the repository lives under. Every runtime requires it, so a repository offering none of the
three gets no catalog and a line on stderr saying why. The same happens outside a repository.
Pass --no-marketplace to skip the step. An init with no --vendor writes no catalog either.
Re-running init folds the entry back in rather than replacing the file. The marketplace name, the
owner, and every other plugin’s entry stay as they are, including edits you made by hand — only this
plugin’s entry is re-derived.
marketplace init covers a repository
Section titled “marketplace init covers a repository”universal-plugin marketplace init --claude --codex --copilot --cursorThis one discovers plugins instead of registering a single one: every <scan-root>/<dir>/plugin.json
below plugins/, or below each --plugin-scan-dir you name. With no target flags it writes all
four catalogs. --dry-run prints the plan, and a catalog that differs from what would be generated
stops the run until you pass --force, so a hand-edited file is never replaced silently. With
--force, each hand-set field or entry it drops is named on stderr, such as owner.email,
description, or plugins[alpha].category.
Discovery walks directories, so it only speaks for plugins that are in them. An entry whose source
is not a local path survives a regeneration untouched, and a discovered plugin whose entry names
a non-local source keeps that source with its derived metadata refreshed around it. So a plugin
shipped through npm keeps pointing at npm, and an entry marketplace add wrote is not a deletion
waiting for the next --force. What discovery owns it still owns: a local-path entry it no longer
finds is dropped. A catalog’s allowCrossMarketplaceDependenciesOn is kept too: discovery cannot
derive it, and without it Claude Code refuses every cross-marketplace dependency.
marketplace add lists a plugin that lives elsewhere
Section titled “marketplace add lists a plugin that lives elsewhere”universal-plugin marketplace add npm:repobuddy --description "Repo automation"init describes the repository. add describes everything else, which is what turns a repository
into a curated marketplace rather than only its own plugins’ home. One positional says where the
plugin lives, and the command reads it by shape:
| Spec | Source written |
|---|---|
./plugins/alpha |
"./plugins/alpha" |
cyberuni/universal-plugin |
{ "source": "github", "repo": "cyberuni/universal-plugin" } |
https://example.com/o/r.git |
{ "source": "url", "url": "…" } |
npm:repobuddy, @cyberuni/upx |
{ "source": "npm", "package": "…" } |
repobuddy@cyberplace |
whatever source that marketplace publishes |
Two shapes collide. plugins/alpha reads as a GitHub repository, because owner/repo and a relative
path are the same string and reaching for the filesystem would make it mean different things in
different directories — write ./plugins/alpha or pass --path. And a leading @ is a scope, so
@cyberuni/upx is a package while upx@cyberplace is a marketplace entry. --path, --npm,
--github, --url, and --from-marketplace each force the reading.
owner/repo and a git URL name a whole repository. For a monorepo that publishes several plugins,
--subdir says which directory is the one, turning the source into git-subdir and naming the entry
after that directory:
universal-plugin marketplace add cyberuni/cyber-sdd --subdir plugins/aced# aced -> { "source": "git-subdir", "url": "https://github.com/cyberuni/cyber-sdd.git", "path": "plugins/aced" }--ref and --sha pin a git source to a branch, tag, or commit. Both apply to url, github, and
git-subdir only — an npm package is pinned by version, a path by what is on disk — and a --sha
must be the full 40-character hash the schema requires.
Only a repository path installs everywhere. Claude Code takes the schema’s full tagged set, Codex takes npm, and Copilot CLI and Cursor take neither:
target status entry reasonclaude added repobuddycodex added repobuddycopilot skipped repobuddy npm source is not supported by copilotcursor skipped repobuddy npm source is not supported by cursorA target that cannot resolve the source gets no entry at all. That is the same rule as validation: a catalog is read in someone else’s terminal, so a source a runtime refuses is a failure far from here.
Nothing is fetched. Metadata comes from the plugin’s own plugin.json for a path, from an installed
node_modules copy for a package, from the entry being copied for a marketplace spec, and otherwise
from --description, --version, --homepage, --repository, --license, and --keywords.
When the entry still lacks a description, homepage, repository, license, or keywords,
stderr names the flags that would fill them, and each row in --format json lists them as missing.
<plugin>@<marketplace> has no source type in the schema, so the entry is resolved and copied. The
marketplace has to be readable: one the runtime has already added is found under
~/.claude/plugins, and --from <dir> names a checkout of one that is not installed.
An entry whose source is a ./ path is rewritten rather than copied. That path resolves against
the other marketplace’s root, which your repository is not — but it names a location inside a
repository whose URL is known:
| Entry in the other marketplace | Written into your catalog |
|---|---|
./plugins/aced in cyberuni/cyberplace |
{ "source": "git-subdir", "url": "https://github.com/cyberuni/cyberplace.git", "path": "plugins/aced" } |
./ in unional/skills |
{ "source": "github", "repo": "unional/skills" } |
The origin comes from what the runtime recorded for that marketplace, falling back to the clone’s own git remote. One with neither stops the run rather than writing a path that resolves nowhere.
The catalog is created if the repository has none, named and owned the way init names it —
--owner is usually what a curating repository needs, since it has no plugin manifest of its own.
An entry already listed differently stops the run until you pass --force.
marketplace update changes one entry in place
Section titled “marketplace update changes one entry in place”universal-plugin marketplace update repobuddy --source https://github.com/cyberuni/repobuddy.gitadd --force replaces an entry with what add can derive, so it drops what it cannot: a
category, an author, a field written by hand. update changes only what you name and keeps every
other field, in the order it was in:
| Change | Flags |
|---|---|
| Move to a new source | --source <spec>, read the way add reads its spec, with --path, --npm, --github, --url, and --subdir |
| Move a pin | --ref <ref>, --sha <sha> |
| Set one field | --description, --version, --homepage, --repository, --license, --keywords, --category |
| Remove a field or a pin | --unset <field>, repeatable; --unset ref and --unset sha remove a pin |
A new git source keeps the pin the old one carried, unless you pass --ref or --sha with it:
switching from the github shorthand to an https url does not change which commit installs.
--ref alone keeps an existing sha, so pass --unset sha when the new ref moves past it:
universal-plugin marketplace update aced --ref v1.3.0 --unset shaThe new source reaches each runtime in the form it installs, as with add. A runtime that cannot
install it is reported skipped and keeps the entry it had; a Copilot CLI or Cursor without a catalog
of its own gets one written to shield it from the Claude catalog. A catalog that does not list the
entry is skipped too, and an entry no selected catalog lists stops the run with a pointer to add.
The Codex catalog carries only version and category of the field flags.
Every catalog is validated before anything is written, with the checks marketplace validate runs.
An update that would introduce an issue stops and writes nothing; an issue that was already there is
left for validate to report. --dry-run shows the plan.
marketplace remove drops an entry
Section titled “marketplace remove drops an entry”universal-plugin marketplace remove repobuddyThe inverse of add. It drops the entry from every selected catalog that lists it and keeps
everything else. A catalog that does not list the entry is skipped, and an entry no selected
catalog lists stops the run.
Every catalog is validated before anything is written. If a plugin still listed depends on the entry,
the run stops. Pass --force to remove it anyway, with a warning naming the dependent plugin.
--dry-run shows the plan, and each row is removed, planned, or skipped.
If the entry’s ./ path still holds a plugin.json, the command warns: plugin build or
marketplace init will list the plugin again. Delete the directory, or leave it out of the scan.
marketplace set edits the catalog’s own fields
Section titled “marketplace set edits the catalog’s own fields”universal-plugin marketplace set --allow-dependencies-on other-marketplaceupdate changes an entry. set changes the catalog’s top-level fields in place and keeps the rest:
| Change | Flags | Catalogs |
|---|---|---|
| Allow or stop allowing a marketplace’s plugins as dependencies | --allow-dependencies-on <marketplace>, --disallow-dependencies-on <marketplace>, repeatable |
Claude only |
| Describe the catalog | --description |
Claude, Copilot, Cursor |
| Name the owner | --owner, --owner-email, --owner-url |
Claude, Copilot, Cursor |
| Remove a field | --unset description, owner.email, owner.url, or allowCrossMarketplaceDependenciesOn, repeatable |
as above |
The dependency allowlist is Claude-only because Claude Code is the only runtime that resolves
dependencies. An allowlist that ends up empty drops the key, and a new key is written before
plugins. Codex carries none of the other fields, so its catalog is skipped.
Every catalog is validated before anything is written. Each row is updated, unchanged,
planned, or skipped, and carries the fields it touched. --dry-run shows the plan.
marketplace validate checks what the repository carries
Section titled “marketplace validate checks what the repository carries”universal-plugin marketplace validateA catalog is read at install time, in someone else’s terminal. This command moves the refusal to the repository: it reads each catalog and checks it against the schema its runtime loads — the official Claude Code marketplace schema for Claude Code, Cursor, and Copilot CLI, and Codex’s own shape for Codex.
Each target is reported valid, invalid, or missing; --required makes a missing catalog a
failure. The exit status is 1 when any selected catalog is invalid, and every issue names the key and
the value to write instead:
error: catalog ".claude-plugin/marketplace.json" does not match the marketplace schema: owner must be an object with a name, not string — write { "name": "Ari Vance" } plugins[0].repository must be a string, not object — write "https://github.com/o/r.git"Those two are the shapes that reach a repository unnoticed, because both are what package.json
carries: an owner string where every runtime requires an object, and an npm repository object
where the catalog requires the URL. Generation reduces what it can — an npm repository becomes its
URL, and a field it cannot reduce is omitted rather than written — and refuses to write a catalog that
would still be invalid. Validation is what catches the rest: a file edited by hand, or a ./ source
pointing at a directory that is no longer there.
In the Claude catalog, validation also checks that each listed plugin’s
dependencies can resolve from it. Claude Code resolves a plain
dependency (a bare name, or an object with no marketplace) against the declaring plugin’s own
marketplace. So a plain dependency the catalog does not list means the plugin cannot install from
here. A dependency that names its marketplace is not held to this catalog’s listing, even when it
names this one. A dependency that names a different marketplace is refused unless the catalog lists
that marketplace in allowCrossMarketplaceDependenciesOn:
{ "name": "cyberplace", "allowCrossMarketplaceDependenciesOn": ["other-marketplace"], "plugins": [...]}Only what is on disk is checked: an entry’s own dependencies, and the manifest of a plugin at a ./
source (its built .claude-plugin/plugin.json, or the canonical declaration before a build). A plugin
listed from npm or git is not fetched, so its dependencies are for the
publish-plugin skill to check when it lists the plugin.
Nothing is repaired. A catalog you edited is yours to correct. For a missing allowlist entry, the repair message names the command:
universal-plugin marketplace set --allow-dependencies-on other-marketplaceThe version is derived, never written
Section titled “The version is derived, never written”A catalog entry’s version is copied from the canonical manifest of the plugin its source resolves
to, at generation time. It is not a second number to maintain: on Claude Code the manifest’s version
overrides the entry’s silently, and an entry whose manifest declares no version carries none. A
version left behind on an entry is removed the next time the entry is derived.
Move the version with plugin version <bump>, or with plugin version --from-package where a release
tool owns it. See ADR-0010.
plugin build keeps it that way. Every build re-derives this plugin’s entry in each catalog the
repository already carries, for the vendors it is building, so a version move reaches the catalogs
without a second command. It re-derives the metadata, not the distribution: an entry pointing at an
npm package still points there after a build — plugin version re-derives through plugin build, and so does the
changeset version → plugin version --from-package release script. The build creates no
catalog: it refreshes the ones the repository chose to carry and leaves everything else in them
alone. See ADR-0014.
Developing against Codex
Section titled “Developing against Codex”Codex installs a copy of the plugin, at
~/.codex/plugins/cache/<marketplace>/<plugin>/<version>. Editing the plugin’s files does not reach
that copy, so a change to anything packaged — a skill, a hook, the manifest — needs two steps:
codex plugin add <plugin>@<marketplace> # re-copies the current sourceThen start a new Codex session. The running one keeps the copy it loaded at startup.
That one add is the whole reinstall. Re-running it at the same version overwrites the cached copy,
so neither codex plugin remove nor a version bump is required first, and
codex plugin marketplace upgrade does nothing for a local marketplace.
The version in that cache path is the one the plugin’s manifest carries, not the catalog entry’s:
Codex installs an entry that declares no version just as happily. Keeping the entry’s version equal
to the manifest’s is this project’s rule rather than Codex’s — it stops the catalog from advertising
a version the plugin does not have. Verified against codex-cli 0.147.0; the probes are in
.research/local-marketplaces/
(E-CODEX-M13 to E-CODEX-M17).
Nothing here is published
Section titled “Nothing here is published”These commands write files into the repository. No marketplace is registered, no plugin installed, nothing authenticated or provisioned. The catalog does its job when someone adds the repository as a marketplace.
Sources for the per-runtime facts above, including which were run end to end and which were read out
of a shipped build, are in
.research/local-marketplaces/.