Plugin marketplaces - Claude Code Docs

Plugin marketplaces are catalogs of available plugins that make it easy to discover, install, and manage Claude Code extensions. This guide shows you how to use existing marketplaces and create your own for team distribution.

Overview

A marketplace is a JSON file that lists available plugins and describes where to find them. Marketplaces provide:

• Centralized discovery: Browse plugins from multiple sources in one place
• Version management: Track and update plugin versions automatically
• Automatic updates: Keep plugins current with per-marketplace auto-update settings
• Team distribution: Share required plugins across your organization
• Flexible sources: Support for git repositories, GitHub repos, local paths, and package managers

Prerequisites

• Claude Code installed and running
• Basic familiarity with JSON file format
• For creating marketplaces: Git repository or local development environment

Add and use marketplaces

Add marketplaces using the /plugin marketplace commands to access plugins from different sources:

Add GitHub marketplaces

/plugin marketplace add owner/repo

Add Git repositories

/plugin marketplace add https://gitlab.com/company/plugins.git

Add local marketplaces for development

/plugin marketplace add ./my-marketplace

/plugin marketplace add ./path/to/marketplace.json

/plugin marketplace add https://url.of/marketplace.json

Install plugins from marketplaces

Once you’ve added marketplaces, install plugins directly:

/plugin install plugin-name@marketplace-name

Verify marketplace installation

After adding a marketplace:

1. List marketplaces: Run /plugin marketplace list to confirm it’s added
2. Browse plugins: Use /plugin to see available plugins from your marketplace
3. Test installation: Try installing a plugin to verify the marketplace works correctly

Example plugin marketplace

Claude Code maintains a marketplace of demo plugins. These plugins are examples of what’s possible with the plugin system.

/plugin marketplace add anthropics/claude-code

Configure team marketplaces

Set up automatic marketplace installation for team projects by specifying required marketplaces in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    },
    "project-specific": {
      "source": {
        "source": "git",
        "url": "https://git.company.com/project-plugins.git"
      }
    }
  }
}

When team members trust the repository folder, Claude Code automatically installs these marketplaces and any plugins specified in the enabledPlugins field.

Enterprise marketplace restrictions

For organizations requiring strict control over plugin sources, enterprise administrators can restrict which plugin marketplaces users are allowed to add using the strictKnownMarketplaces setting in managed settings. Managed settings file locations:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux and WSL: /etc/claude-code/managed-settings.json
• Windows: C:\ProgramData\ClaudeCode\managed-settings.json

Restriction behavior: When strictKnownMarketplaces is configured in managed settings:

• Undefined (default): No restrictions - users can add any marketplace
• Empty array []: Complete lockdown - users cannot add any new marketplaces
• List of sources: Users can only add marketplaces that match the allowlist exactly

Basic examples: Disable all marketplace additions:

{
  "strictKnownMarketplaces": []
}

Allow specific marketplaces only:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "company/approved-plugins"
    },
    {
      "source": "github",
      "repo": "company/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://internal.company.com/plugins/marketplace.json"
    }
  ]
}

Key characteristics:

• Enforced BEFORE network/filesystem operations
• Uses exact matching (including optional ref and path fields for git sources)
• Cannot be overridden by user or project settings
• Only affects adding NEW marketplaces (previously installed marketplaces still work)

See strictKnownMarketplaces reference for complete configuration details, including all six supported source types, exact matching rules, and comparison with extraKnownMarketplaces.

Create your own marketplace

Build and distribute custom plugin collections for your team or community.

Prerequisites for marketplace creation

• Git repository (GitHub, GitLab, or other git hosting)
• Understanding of JSON file format
• One or more plugins to distribute

Create the marketplace file

Create .claude-plugin/marketplace.json in your repository root:

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Marketplace schema

Required fields

Optional metadata

Plugin entries

Required fields:

Optional plugin fields

Standard metadata fields:

Component configuration fields:

^{1 - When strict: true (default), the plugin must include a plugin.json manifest file, and marketplace fields supplement those values. When strict: false, the plugin.json is optional. If it’s missing, the marketplace entry serves as the complete plugin manifest.}

Plugin sources

Relative paths

For plugins in the same repository:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

GitHub repositories

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Git repositories

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Advanced plugin entries

Plugin entries can override default component locations and provide additional metadata. Note that ${CLAUDE_PLUGIN_ROOT} is an environment variable that resolves to the plugin’s installation directory (for details see Environment variables):

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "[email protected]"
  },
  "homepage": "https://docs.company.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Host and distribute marketplaces

Choose the best hosting strategy for your plugin distribution needs.

Host on GitHub (recommended)

GitHub provides the easiest distribution method:

1. Create a repository: Set up a new repository for your marketplace
2. Add marketplace file: Create .claude-plugin/marketplace.json with your plugin definitions
3. Share with teams: Team members add with /plugin marketplace add owner/repo

Benefits: Built-in version control, issue tracking, and team collaboration features.

Host on other git services

Any git hosting service works for marketplace distribution, using a URL to an arbitrary git repository. For example, using GitLab:

/plugin marketplace add https://gitlab.com/company/plugins.git

Use local marketplaces for development

Test your marketplace locally before distribution:

/plugin marketplace add ./my-local-marketplace

/plugin install test-plugin@my-local-marketplace

Manage marketplace operations

List known marketplaces

Shows all configured marketplaces with their sources and status.

Update marketplace metadata

/plugin marketplace update marketplace-name

Refreshes plugin listings and metadata from the marketplace source.

Remove a marketplace

/plugin marketplace remove marketplace-name

Removes the marketplace from your configuration.

Auto-update settings

Claude Code can automatically update marketplaces and their installed plugins at startup. This keeps your plugins current without manual intervention.

How auto-update works

When auto-update is enabled for a marketplace:

1. Marketplace refresh: Claude Code pulls the latest marketplace data (git pull or re-download)
2. Plugin updates: Installed plugins from that marketplace are updated to their latest versions
3. Notification: If any plugins were updated, you’ll see a notification suggesting a restart

Configure auto-update per marketplace

Toggle auto-update for individual marketplaces through the UI:

1. Run /plugin to open the plugin manager
2. Select Marketplaces
3. Choose a marketplace from the list
4. Select Enable auto-update or Disable auto-update

Auto-update behavior

Disable auto-update globally

To disable all automatic updates (both Claude Code and plugins), set the DISABLE_AUTOUPDATER environment variable. See Auto updates for details. When auto-updates are disabled globally:

• No marketplaces or plugins will auto-update
• The auto-update toggle is hidden in the UI
• You can still manually update using /plugin marketplace update

Troubleshooting marketplaces

Common marketplace issues

Marketplace not loading

Symptoms: Can’t add marketplace or see plugins from it Solutions:

• Verify the marketplace URL is accessible
• Check that .claude-plugin/marketplace.json exists at the specified path
• Ensure JSON syntax is valid using claude plugin validate
• For private repositories, confirm you have access permissions

Plugin installation failures

Symptoms: Marketplace appears but plugin installation fails Solutions:

• Verify plugin source URLs are accessible
• Check that plugin directories contain required files
• For GitHub sources, ensure repositories are public or you have access
• Test plugin sources manually by cloning/downloading

Validation and testing

Test your marketplace before sharing:

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

For complete plugin testing workflows, see Test your plugins locally. For technical troubleshooting, see Plugins reference.

Next steps

For marketplace users

• Discover community marketplaces: Search GitHub for Claude Code plugin collections
• Contribute feedback: Report issues and suggest improvements to marketplace maintainers
• Share useful marketplaces: Help your team discover valuable plugin collections

For marketplace creators

• Build plugin collections: Create themed marketplace around specific use cases
• Establish versioning: Implement clear versioning and update policies
• Community engagement: Gather feedback and maintain active marketplace communities
• Documentation: Provide clear README files explaining your marketplace contents

For organizations

• Private marketplaces: Set up internal marketplaces for proprietary tools
• Governance policies: Establish guidelines for plugin approval and security review
• Training resources: Help teams discover and adopt useful plugins effectively

See also

• Plugins - Installing and using plugins
• Plugins reference - Complete technical specifications and schemas
• Plugin development - Creating your own plugins
• Settings - Plugin configuration options
• strictKnownMarketplaces reference - Complete configuration reference for enterprise marketplace restrictions