Manage Claude Code plugins for your organization

​

Pre-install and require plugins

​

Choose a delivery mechanism

• Server-managed settings: set the plugin keys as JSON at Organization settings > Claude Code > Managed settings. Requires an Owner role in your Claude organization. A cloud session fetches these settings before it installs plugins.
• MDM policies: on macOS, deliver a plist whose top-level keys are the settings keys. On Windows, store the whole JSON document as a string in a registry value. The plist domain and the registry key are in Where each mechanism stores the policy.
• Managed settings file: place a managed-settings.json at the platform’s system path. You can also add files to the managed-settings.d/ drop-in directory beside it. The file paths per platform are in Where each mechanism stores the policy, and the drop-in merge rules are in Split a file-based policy across teams.

​

Which managed source applies on a machine

​

Require a marketplace and its plugins

{
  "extraKnownMarketplaces": {
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  }
}

• autoUpdate: true keeps the marketplace and its plugins refreshing in the background, and false turns that off. See Set update policy.
• source: github is one of several source types. A git source takes a url for GitLab or an internal host, and a url source takes the address of a hosted marketplace.json. Every source shape is in the marketplace reference.

• Marketplaces: a managed marketplace entry replaces a lower-precedence entry with the same name, and the two entries’ fields don’t merge.
• --plugin-dir copies: --plugin-dir loads a plugin from a local directory for one session. For what happens when that copy’s name matches a plugin your managed enabledPlugins names, see Name conflicts.

​

Require plugins per repository

• Interactive sessions: Claude Code registers the marketplace only after the contributor accepts the workspace trust dialog for that folder.
• Non-interactive -p runs: the entries apply only in a folder whose trust the user already accepted interactively, or whose hasTrustDialogAccepted flag you set in ~/.claude.json.

​

When each surface applies the plugin keys

​

Confirm the rollout

• On one machine: start Claude Code and run /plugin. The marketplace and the plugins are listed.
• In CI: run claude -p with --output-format stream-json --verbose. The init event lists the loaded plugins under plugins.

​

Seed containers and CI

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install code-formatter@your-marketplace

• Read-only: Claude Code never writes to the seed and forces autoUpdate off for seed marketplaces.
• Seed entries take precedence: on each startup, a marketplace declared in the seed overwrites the user’s entry of the same name. Users opt out of a seed plugin with claude plugin disable, not by removing the marketplace.
• Update and remove fail: claude plugin marketplace update <name> and remove without --scope on a seed marketplace fail with a message that names the seed directory.
• Policy still applies: the allowlist and blocklist check a seed marketplace’s recorded source too. Allow the source you built the seed from.

​

Restrict what users can install

• Before a download: the lists apply when a user adds a marketplace and on every install, update, refresh, and auto-update.
• At session start: the lists apply again to plugins that are already installed, so an installed plugin whose marketplace source no longer matches doesn’t load. /plugin lists it with Marketplace "<name>" is not in the allowed marketplace list or Marketplace "<name>" is blocked by enterprise policy.

• The claude.ai admin console: Claude Code enforces both lists in the sessions that read server-managed settings. claude.ai also checks them when anyone in your organization adds a new marketplace from a git repository on claude.ai, or from Customize in the Claude Desktop app outside its Code tab. That covers a marketplace a member adds for their own account and one added for the whole organization under Organization settings > Plugins. claude.ai refuses a repository that the allowlist doesn’t admit or that the blocklist names. It doesn’t re-check a marketplace that was added in either place before you set the lists, and it doesn’t check uploaded plugins.
• A managed settings file, OS-level policy, or other managed source: Claude Code enforces both lists where it reads that source. claude.ai doesn’t read it.

​

Control matrix

• enabledPlugins: you can set it in any scope, and managed settings lock it.
• syncClaudeAiPlugins: each user can also set it in their own user or local settings. See its scope in the settings reference.
• CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: this is an environment variable that you deliver through the managed env block shown under Turn updates off for the whole fleet.

​

Aliases for the marketplace keys

• Version: the aliases require Claude Code v2.1.232 or later, and older clients ignore them. In a file that a mixed fleet reads, keep the canonical names.
• Both spellings set: when a file sets both spellings, the canonical key’s value applies.

​

Allowlist with strictKnownMarketplaces

• github: { "source": "github", "repo": "your-org/approved-plugins" }, with optional ref and path.
• github owner wildcard: { "source": "github", "repo": "your-org/*" } matches every repository under that owner. The * must stand for the whole repository name. Claude Code ignores entries such as */plugins and your-org/tools-* as invalid, so they match nothing. Requires Claude Code v2.1.223 or later.
• git: { "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }, with optional ref and path.
• url: { "source": "url", "url": "https://plugins.example.com/marketplace.json" }, with optional headers.
• file and directory: { "source": "file", "path": "/opt/marketplace/marketplace.json" } or { "source": "directory", "path": "/opt/marketplace/plugins" }, with absolute paths.
• hostPattern: { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }, matched against the host of github, git, and url sources. The pattern matches anywhere in the hostname, so anchor it with ^ and $ as shown to match the whole host. A github source always counts as github.com. Use a hostPattern entry for a GitHub Enterprise Server or GitLab host where developers create their own marketplaces. The GHES page has the worked example.
• pathPattern: { "source": "pathPattern", "pathPattern": "^/opt/approved/" }, matched against the path of file and directory sources. The pattern matches anywhere in the path, so start it with ^ to pin a directory prefix. ".*" allows every local path.
• skills-dir: { "source": "skills-dir" } keeps skills-directory plugins loading while an allowlist is set, and matches no marketplace.

​

How entries match

• An entry without ref doesn’t cover a source with ref: "main".
• An entry for your-org/your-marketplace doesn’t cover a git URL that clones the same repository.
• A trailing slash, a .git suffix, or ssh:// in place of https:// is a different value. When a marketplace can be cloned by more than one URL, prefer a hostPattern entry.

​

Keep skills-directory plugins loading

​

Marketplaces hosted on claude.ai

​

Lock every source out

​

Blocklist with blockedMarketplaces

• Git URLs are canonicalized, so the git@ and https:// forms, .git suffixes, and trailing slashes of one github.com repository all match the same entry.
• A github entry also blocks the equivalent git URL, and the other way around.
• For an owner/* entry, the owner comparison is case-insensitive.
• An entry without ref or path blocks every ref and path of the repositories it matches.

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted-org/*" }
  ]
}

​

Allow the official marketplace and your own

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "your-marketplace": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "code-formatter@your-marketplace": true,
    "deploy-helper@your-marketplace": true
  },
  "disableSideloadFlags": true
}

• The allowlist doesn’t register anything: an extraKnownMarketplaces entry does, and it must itself pass the allowlist. Claude Code refuses to register a managed marketplace whose source the allowlist doesn’t match.
• The official marketplace registers itself only in an interactive terminal session: even there, it registers only when the allowlist permits it. A -p run or a terminal attached to a cloud session never registers it.
• A blocked attempt is remembered: if a machine ever ran under a policy that blocked the official marketplace, Claude Code records the blocked attempt and doesn’t retry after the policy changes. An [] lockdown is one such policy. That machine registers it again only through an extraKnownMarketplaces entry such as the one in this policy, an enabledPlugins entry for one of its plugins, or a manual /plugin marketplace add.

​

Set update policy

​

Turn auto-update on or off per marketplace

• If the managed entry sets the field, Claude Code refuses the user’s /plugin toggle with an error that starts Auto-update for '<name>' is set by.
• If the managed entry leaves the field unset, the user’s toggle persists.

​

Turn updates off for the whole fleet

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

​

Assign release channels to user groups

• Deploy separate endpoint-managed settings, such as a managed settings file or an MDM profile, to each group’s devices. To check whether the per-group file or profile applies on a device that also has an organization-wide source, see How Claude Code combines managed sources.
• Define one Claude apps gateway policy per group. The gateway applies the first policy whose match rule fits a user, so order the policies so that each user reaches their group’s policy. That policy’s extraKnownMarketplaces map doesn’t merge with any other policy’s, so list every marketplace the group needs in it, not only its channel marketplace.

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": { "source": "github", "repo": "your-org/stable-tools" }
    }
  }
}

​

Recommend plugins

​

Audit and review

​

OpenTelemetry events

​

Analytics API

​

Plan for what managed settings can’t enforce

• Per-user or per-group targeting: every plugin key applies to every user who receives the settings. Server-managed settings deliver one configuration per organization. For per-group policy, use separate endpoint-managed settings or gateway policies, as under Assign release channels to user groups.
• Restricting entries inside an allowed marketplace: the allowlist matches marketplace sources. To block one plugin from an allowed marketplace, set it to false in managed enabledPlugins.
• Hiding /plugin: no key disables the command. The nearest equivalent combines an allowlist naming only your marketplace, managed enabledPlugins entries for the plugins you supply, and disableSideloadFlags.
• Gating --plugin-dir through the allowlist: the allowlist doesn’t cover --plugin-dir. disableSideloadFlags does.
• Enforcing the claude.ai plugin toggles through these keys: Organization settings > Plugins & skills doesn’t set the keys on this page. What members and your organization turn on there reaches the CLI as synced plugins, which have their own controls.

​

Troubleshoot policy

• The managed file didn’t parse: when a managed-settings.json isn’t valid JSON, Claude Code refuses to start and prints an error naming the file. A file that parses but has one invalid entry keeps the rest of its policy. See Invalid entries in managed settings.
• The managed source didn’t load: run /status and look for Enterprise managed settings in the Setting sources line. If it’s missing, the source didn’t load.
• A user reports blocked by enterprise policy: the message names the marketplace or its source. For an allowlist, it also lists the allowed sources. The user-facing entries are on Troubleshoot plugins.
• A plugin the user disabled in ~/.claude/settings.json still loads: another settings source re-enabled it, such as a managed enabledPlugins entry that force-enables it. /plugin and claude plugin list show Disabled in ~/.claude/settings.json but still loads with that settings source.

​

Next steps

• Marketplace reference: the source values extraKnownMarketplaces, strictKnownMarketplaces, and blockedMarketplaces accept
• Host and maintain a marketplace: run the marketplace your policy points at
• Plugin security and trust: what a plugin can do on a machine and how to review one before installing
• Server-managed settings: deliver these keys from the claude.ai admin console
• Troubleshoot plugins: the messages users see when policy blocks them