Host and maintain a marketplace

​

Host your marketplace

​

Register the marketplace for everyone in a repository

​

Avoid relative-path entries in a URL-hosted marketplace

​

Edit plugins in place on a shared directory

​

Keep plugin files out of Git LFS

​

Share files within a marketplace with symlinks

• Within the plugin’s own directory: the symlink is preserved as a relative symlink in the cache, so it keeps resolving to the copied target at runtime.
• Elsewhere within the same marketplace: the symlink is dereferenced. The target’s content is copied into the cache in its place. This lets a meta-plugin’s skills/ directory link to skills defined by other plugins in the marketplace.
• Outside the marketplace: the symlink is skipped for security.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Distribute through organization settings

• Marketplace repository: on github.com and gitlab.com, it must be private or internal
• Plugin sources: each plugin source must be of type github, url, or git-subdir, or a relative path that starts with ./
• Top-level bin/ directory: claude.ai rejects a plugin that has one and syncs the rest of the marketplace. The error message starts with Plugin contains a top-level bin/ directory. Keep executables in another directory, such as scripts/, and reference them as ${CLAUDE_PLUGIN_ROOT}/scripts/<name> from your hooks or MCP server configs

​

Grant access to a private marketplace

• GitHub owner/repo: Claude Code probes ssh -T git@github.com and clones over SSH when the probe succeeds. If the probe fails, or the SSH clone itself fails, it clones over HTTPS. Users on machines without a GitHub SSH key can set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 to skip the probe and clone over HTTPS.
• git@host:path.git: SSH.
• https://example.com/repo.git: HTTPS.

• SSH: the key must work without a passphrase prompt, for example because it’s loaded in ssh-agent. The host must already be in known_hosts.
• HTTPS: Claude Code leaves the user’s git credential helper enabled but forbids it from prompting. A credential the helper already stores works; one it would have to ask for fails. On GitHub, gh auth login followed by gh auth setup-git stores one.

​

Serve users who have no git-host account

• archive: a zip downloaded over HTTPS. Users need neither git nor an account, only network access to the URL. Requires Claude Code v2.1.224 or later. Pin each archive with sha256 so Claude Code refuses a changed download. To send credentials with the download, see Authenticate archive downloads.
• A public git repository: Claude Code clones a public url or git-subdir source over HTTPS without credentials when the entry gives an https:// URL. For a github source, or a git-subdir source written as owner/repo, users without a GitHub SSH key set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

​

What background auto-update does with credentials

• SSH remotes: a key loaded in ssh-agent authenticates the check.
• HTTPS remotes with a stored credential: a helper that can supply a stored credential without prompting authenticates the check. Git Credential Manager, the macOS Keychain helper, and git-credential-store work this way once they hold a credential for the host.
• HTTPS remotes with a helper that needs to prompt: the helper can’t answer in the background. The update fails quietly and the existing checkout stays in place, so the user’s plugins keep working from the last synced state.

• The checkout is up to date: Claude Code leaves it as it is.
• The check finds new commits, or fails because it can’t reach or authenticate to the remote: Claude Code clones the marketplace again and replaces the existing checkout with the new clone. If that clone fails, the existing checkout stays in place. The re-clone can time out on large repositories.

• Store a credential: sign in to the credential helper first so it holds a credential for the host. For GitHub, run gh auth login, then gh auth setup-git.
• Keep the checkout on failure: if the user sets CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1, Claude Code keeps the existing checkout without attempting the re-clone when the background check can’t reach or authenticate to the remote. Plugins keep working from the last synced state.

​

Roll out to a whole company

• Entry sources that need no git account: Serve users who have no git-host account
• A pre-populated plugins directory: Seed containers and CI, which also serves users who have no git-host account
• claude.ai organization settings: Distribute through organization settings, where your users’ git credentials aren’t involved

​

Keep users up to date

​

Turn on auto-update

• Tell users to turn it on: each user goes to Marketplaces in /plugin, selects your marketplace, and selects Enable auto-update.
• Ask an admin to set it: if an admin sets "autoUpdate": true on your marketplace’s extraKnownMarketplaces entry in managed settings, it’s on for everyone who receives those settings. See Set update policy.

​

Release a new version

• Bump version on each release: users stay on their cached copy until the string changes. If you set "version": "1.0.0" and push new commits without changing it, users don’t receive them.
• Omit version: users track your commits instead. Leave version out of both plugin.json and the marketplace entry.

​

Hold users on one version

• ref and sha on the plugin entry: ref names a branch or tag and sha names a commit for a github, url, or git-subdir source. See Plugin sources.
• #<ref> on the add command: users who add your-org/your-marketplace#stable get that branch or tag of the catalog. For two release lines at once, see Run release channels.
• <plugin>--v<version> tags: a dependency’s version range resolves against these tags. See Release a plugin that others depend on.

​

Change the command of a command source

• No more background runs: the once-per-session run of the command stops for that user, so the tool’s new output doesn’t reach them.
• An entry in the /plugin Errors tab: the entry shows the new command and the claude plugin update command to run.

​

Run release channels

{
  "name": "stable-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "stable" } }
  ]
}

{
  "name": "latest-tools",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": { "source": "github", "repo": "your-org/code-formatter", "ref": "latest" } }
  ]
}

​

Rename or remove a plugin

​

Migrate users with a renames map

{
  "name": "your-marketplace",
  "owner": { "name": "Your Org" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Renamed entry: the plugin loads under its new name. claude plugin list and the plugin’s details under /plugin show Renamed to "code-formatter" in the "your-marketplace" marketplace once, and Claude Code rewrites the old key to the new one in enabledPlugins and pluginConfigs in the user, project, and local settings scopes.
• null entry: the old key is dropped from those scopes and the user sees Removed from the "your-marketplace" marketplace.
• Enabled in managed settings: the plugin still loads under its new name, but Claude Code can’t rewrite managed settings, so the notice recurs until an admin updates enabledPlugins there.

​

Uninstall removed plugins from users’ machines

1. Compares what users installed from your marketplace against the entries and the renames map, and treats any plugin that is neither listed nor renamed as removed.
2. Uninstalls each removed plugin from the user, project, and local scopes. Plugins that only managed settings installed stay in place.
3. Lists each removed plugin under a Flagged heading in /plugin with the status Removed from marketplace.

​

Authenticate archive downloads

• The marketplace’s url source: the url source you registered the marketplace from, such as an extraKnownMarketplaces entry.
• The plugin’s entry: on Claude Code v2.1.238 or later, you can set it on the plugin’s marketplace.json entry instead, beside source.

​

Add a headersHelper to a plugin entry

{
  "name": "my-plugin",
  "description": "Formatting commands for internal services",
  "strict": false,
  "source": {
    "source": "archive",
    "url": "https://registry.example.com/plugins/my-plugin-2.1.0.zip"
  },
  "headersHelper": "/opt/bin/mint-registry-token.sh"
}

​

Write the headersHelper command

• Command text: at most 500 characters of printable ASCII, with no run of four or more spaces.
• Output: print one JSON object of header names and string values on stdout, then exit 0 within 10 seconds.
• Shell and working directory: Claude Code runs the command through sh, or through cmd.exe on Windows. The working directory is the configuration directory, which is ~/.claude or CLAUDE_CONFIG_DIR. Give an absolute path or a command on PATH, because a relative path resolves against that directory, not the user’s project.
• Variables Claude Code removes: when the command is set in a marketplace.json entry, or in a project’s .claude/settings.json or .claude/settings.local.json, Claude Code removes from the environment every variable whose name looks like a credential, by the same rule it applies to an MCP headersHelper. ANTHROPIC_API_KEY and MY_REGISTRY_TOKEN are both removed, so have the command read its credential from a file or a credential store. This removal doesn’t apply to a command set in user settings, a --settings file, or managed settings.
• Variables Claude Code sets: CLAUDE_CODE_MARKETPLACE_URL and CLAUDE_CODE_MARKETPLACE_NAME for a url source’s command, and CLAUDE_CODE_PLUGIN_NAME and CLAUDE_CODE_PLUGIN_ARCHIVE_URL for an entry’s command. CLAUDE_CODE_MARKETPLACE_NAME is unset on the first fetch after a user adds a marketplace by URL, because that fetch is what supplies the name.

{"Authorization": "Bearer eyJhbGciOiJSUzI1NiJ9"}

​

When Claude Code skips a headersHelper command or drops its output

• Command fails: if the command exits non-zero, runs past 10 seconds, or prints anything other than a JSON object of string values, the fetch or download the command was run for doesn’t happen.
• Marketplace URL doesn’t start with https://: that url source’s command doesn’t run, and requests carry only the headers listed in its headers field.
• Redirect leaves the origin: when a download is redirected off the archive URL’s origin, the redirected request carries no headers values or command output from either the marketplace url source or the plugin entry.
• Entry sets a routing or identity header: Claude Code drops request-routing and client-identity names such as Host, Cookie, and X-Forwarded-* from an entry’s headers and command output, and keeps authentication names such as Authorization. Every marketplace.json entry is filtered this way. For an inline plugin entry in settings, see extraKnownMarketplaces.
• Command set in an --add-dir directory’s settings: the command is ignored, on a url source and on an inline plugin entry alike, and only that file’s headers are sent.
• Managed settings block the command: setting disableCommandPluginSources to true blocks headersHelper commands, and allowManagedHooksOnly blocks them too unless disableCommandPluginSources is explicitly false. Under either block, Claude Code still runs the command for a marketplace that managed settings themselves declare.

​

How users accept a headersHelper command

​

Installs and updates that refuse a command instead of asking

• Installing several plugins at once, from a plugin suggestion, or as another plugin’s dependency: Claude Code refuses the plugin that has the command and directs the user to that plugin’s own view in /plugin. The other plugins in a bulk install still install. A plugin that depends on the refused plugin fails to install until the user installs the refused plugin by itself.
• Background auto-update, or session start for a plugin whose archive was never downloaded: Claude Code lists the plugin in the /plugin Errors tab so the user knows to install or update it themselves.

​

When a marketplace url source’s command runs

​

Depend on and recommend other plugins

• Version ranges: a dependency can carry a semver range.
• Cross-marketplace dependencies: a dependency from another marketplace installs only when your marketplace lists that marketplace in allowCrossMarketplaceDependenciesOn.

​

Work around what a marketplace can’t do

• Restrict what else users install: the marketplace allowlist is a managed setting, strictKnownMarketplaces. See Restrict what users can install.
• Install or enable a plugin without the user asking: no entry field installs a plugin. Managed enabledPlugins does that for a fleet; see Pre-install and require plugins.
• Show different entries to different users: entries carry no audience field, and every user who adds the marketplace sees the whole catalog. Host separate marketplaces for separate audiences.
• Mark a plugin deprecated: there is no deprecation state. The option is to remove the entry, map its name to null in renames, and optionally set forceRemoveDeletedPlugins.
• Turn on auto-update for your users: each user turns it on under Marketplaces in /plugin, or an admin sets autoUpdate in managed settings. See Turn on auto-update.
• Carry git credentials: no marketplace field holds a git token. Access to a git-hosted marketplace or plugin follows the user’s git setup, per Grant access to a private marketplace. For archive sources, an entry can set headers or headersHelper instead.

​

Next steps

• Marketplace reference: marketplace.json fields, source types, and validation messages
• Manage plugins for your organization: require, restrict, or seed your marketplace across your organization’s machines
• Plugin dependencies: tag releases so plugins that depend on yours can resolve versions
• Troubleshoot plugins: the errors your users see when adding or updating from your marketplace