How to Configure the Plugin Marketplace for Claude Code

You configure the plugin marketplace in Claude Code by editing the marketplaces array in settings.json or using the /plugin marketplace CLI commands to add, remove, or update Git-based manifest sources.

The anthropics/claude-code repository implements a marketplace discovery system that aggregates plugin manifests from multiple sources. To configure the plugin marketplace for Claude Code, you define external sources in your project's settings.json file—located at the project root or specified via the CLAUDE_SETTINGS_PATH environment variable—or interactively through CLI commands. These user-defined marketplaces merge with the core manifest at .claude-plugin/marketplace.json to populate the plugin discovery interface.

Configure Marketplaces via settings.json

To persist marketplace configurations, add a marketplaces array to your settings.json. Each entry requires a name, source URL, and sourceType (typically "git"), with optional branch pinning and autoUpdate toggles.

{
  "marketplaces": [
    {
      "name": "my-custom-plugins",
      "source": "https://github.com/your-org/custom-plugins",
      "sourceType": "git",
      "branch": "main",
      "autoUpdate": true
    }
  ]
}

The source field must point to a repository containing a valid marketplace.json file. When autoUpdate is enabled, Claude Code periodically fetches the latest manifest from the specified branch.

Manage Marketplaces with CLI Commands

For dynamic configuration without manually editing JSON, use the /plugin marketplace commands.

Adding a Marketplace via CLI

Use the add subcommand followed by the repository path and an optional ref specifier:

/plugin marketplace add your-org/custom-plugins@main

The @ separator specifies a Git ref (branch, tag, or commit). Alternative syntax uses # for refs:

/plugin marketplace add awesome/claude-plugins#v2.0

Listing and Refreshing Sources

/plugin marketplace list    # Display all configured sources

/plugin marketplace update # Refresh remote manifests from all sources

Enforce Security with strictKnownMarketplaces

Administrators can restrict which repository URLs are permissible by defining the strictKnownMarketplaces array in settings.json. This prevents arbitrary code execution by rejecting marketplace additions that do not match the specified glob patterns, as demonstrated in examples/settings/settings-strict.json.

{
  "strictKnownMarketplaces": [
    "https://github.com/your-org/*",
    "https://gitlab.com/trusted-team/*"
  ]
}

Any /plugin marketplace add command referencing a URL outside these patterns triggers an informative error.

Summary

• Marketplace configuration resides in the marketplaces array of settings.json or via the /plugin marketplace CLI commands.
• The core manifest at .claude-plugin/marketplace.json provides default bundled plugins and merges with user-defined sources.
• Use strictKnownMarketplaces to implement a whitelist of allowed repository patterns.
• The autoUpdate field controls whether Claude Code periodically refreshes remote manifests from Git sources.
• CLI commands support @ or # syntax for pinning specific Git refs.

Frequently Asked Questions

How do I specify a particular branch or tag for a marketplace?

When adding a marketplace via CLI, append @branch-name or #tag-name to the repository path (e.g., /plugin marketplace add org/[email protected]). In settings.json, use the branch field to pin the ref.

Where does Claude Code look for settings.json?

By default, Claude Code loads settings.json from the project root. You can override this by setting the CLAUDE_SETTINGS_PATH environment variable to a custom file location before starting the session.

What happens if autoUpdate is disabled?

When autoUpdate is set to false in a marketplace entry, Claude Code uses the cached manifest from the initial load or last manual /plugin marketplace update command, never automatically fetching new changes from the remote.

Can I use local directories instead of Git URLs?

Yes. While sourceType: "git" is common for remote repositories, the marketplace system supports local paths as alternative sourceType values to reference manifests on the filesystem, though this is typically reserved for development workflows.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}