Plugins and skills

Enable plugins, register marketplaces, restrict which plugin sources an organization allows, and control which skills load. For installing and building plugins, see Plugins.

disableBundledSkills

Turn off the skills and workflows included with Claude Code. Claude Code removes bundled skills and workflows entirely, while built-in commands such as /init stay typable but are hidden from the model.

• Scope: Any file
• Type: Boolean
  • true: Claude Code removes bundled skills and workflows and hides built-in commands such as /init from the model
  • false: bundled skills load
• Default: unset, so bundled skills load
• Per-session overrides: CLAUDE_CODE_DISABLE_BUNDLED_SKILLS set to 1 turns bundled skills off for one session; whichever of the two turns them off, the other can't turn them back on

{
  "disableBundledSkills": true
}

Skills from plugins, .claude/skills/, and .claude/commands/ are unaffected. /doctor stays typable like the built-in commands; to hide it, set DISABLE_DOCTOR_COMMAND instead.

disableSkillShellExecution

Turn off inline shell execution for !`...` and ```! blocks in skills and custom commands from user, project, plugin, or additional-directory sources. Claude Code replaces each command with [shell command execution disabled by policy] instead of running it.

• Scope: Any file. A true in managed settings can't be overridden by false elsewhere.
• Type: Boolean
  • true: Claude Code replaces each inline shell command with [shell command execution disabled by policy] instead of running it
  • false: inline shell runs
• Default: unset, so inline shell runs

{
  "disableSkillShellExecution": true
}

Bundled skills and skills deployed through managed settings are unaffected.

skillOverrides

Hide or collapse a skill without editing its SKILL.md. Claude Code applies the value under each skill's name to the skill list Claude sees and to your / autocomplete.

• Scope: Any file. The /skills menu writes to .claude/settings.local.json.
• Type: object mapping skill name to one of:
  • "on": Claude sees the skill and you can type /name
  • "name-only": Claude sees the skill by name without its description
  • "user-invocable-only": Claude doesn't see the skill, but you can still type /name
  • "off": Claude doesn't see the skill and /name is hidden from autocomplete
• Default: unset, so every skill is "on"

This example lists legacy-context to Claude by name only and hides deploy from Claude and from / autocomplete:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Overrides don't apply to plugin skills, which you manage through /plugin.

In managed settings and files passed with --settings, a key on a bundled skill's alias, such as checkup for /doctor, also applies to the skill; see how alias keys combine with keys on the skill's own name.

syncClaudeAiSkills

Turn off the download of the skills you enable on claude.ai. Claude Code downloads them into ~/.claude/skills/synced/ when you run it in non-interactive mode with the -p flag and CLAUDE_CODE_SYNC_SKILLS set. Set false to stop that download and hide the skills it already synced. Claude Code honors only false: true is the same as unset and doesn't turn syncing on.

• Scope: User, local, or managed. A repository can't turn it off for you.
• Type: Boolean
  • false: Claude Code stops downloading synced skills and hides the ones already in ~/.claude/skills/synced/. In user or managed settings, it also moves them to ~/.claude/skills/.trash/
  • true: the same as unset
• Default: unset, so a non-interactive run with CLAUDE_CODE_SYNC_SKILLS set downloads the skills

This example keeps a machine from downloading the account's skills, whatever a session sets in its environment:

{
  "syncClaudeAiSkills": false
}

allowedChannelPlugins

Choose which channel plugins can push messages into sessions in your organization. When you set it, Claude Code uses your list in place of the default Anthropic allowlist; each entry names a plugin and the marketplace it comes from.

• Scope: Managed
• Type: array of objects, each with marketplace and plugin strings. An entry can instead be a "plugin@marketplace" string such as "telegram@claude-plugins-official", which Claude Code treats as the equivalent object. The string form requires Claude Code v2.1.267 or later; earlier versions reject the whole allowedChannelPlugins value when it contains one
• Default: unset, so Claude Code uses the default Anthropic allowlist

This example turns channels on and allows only the Telegram plugin from the official Anthropic marketplace:

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" }
  ]
}

An empty array blocks every channel plugin.

This key takes effect once channels pass the channelsEnabled gate for the account: on Team and Enterprise plans, and on Console accounts with managed settings, that means channelsEnabled: true. See Restrict which channel plugins can run.

blockedMarketplaces

Block plugin marketplace sources for your organization. Claude Code checks the blocklist on marketplace add and on plugin install, update, refresh, and auto-update, so a marketplace someone added before you set the policy can't be used to fetch plugins either. Blocked sources are checked before download, so they never touch the filesystem.

• Scope: Managed
• Type: array of marketplace source objects, in the same forms as strictKnownMarketplaces
• Default: unset, so no marketplace is blocked

This example blocks one GitHub repository as a marketplace source:

{
  "blockedMarketplaces": [
    { "source": "github", "repo": "untrusted/plugins" }
  ]
}

A github entry may use the owner-wildcard form "owner/*" to block every repository under that GitHub owner, which requires Claude Code v2.1.223 or later. Add \{ "source": "skills-dir" \} to stop Claude Code loading @skills-dir plugins from ~/.claude/skills/ without restricting any marketplace. See Managed marketplace restrictions.

channelsEnabled

Allow channels for your organization. On claude.ai Team and Enterprise plans, Claude Code blocks channels until you set this to true. For Anthropic Console accounts that authenticate with an API key, channels are allowed by default. If your organization deploys managed settings, Claude Code blocks channels on those accounts too until you set this key to true.

• Scope: Managed
• Type: Boolean
  • true: Claude Code allows channels for your organization
  • false: the same as unset; whether channels are blocked depends on your plan, as the Default says
• Default: unset; channels are blocked on Team and Enterprise plans and on Console accounts with managed settings, and allowed on Pro and Max plans and on Console accounts without managed settings

{
  "channelsEnabled": true
}

To restrict which plugins can register as channels once they're enabled, set allowedChannelPlugins. See Enterprise controls.

disableCommandPluginSources

Block the command plugin source, which installs a plugin by running a marketplace-declared command on the user's machine. When you set it to true, Claude Code never runs the command, doesn't install or update command-sourced plugins, and stops loading the ones already installed. Set it to false to allow them explicitly. Whenever it blocks command sources, whether you set it to true or leave it unset under allowManagedHooksOnly, it also blocks marketplace headersHelper commands, except for a marketplace that managed settings themselves declare. Requires Claude Code v2.1.229 or later, and the headersHelper block requires v2.1.238 or later.

• Scope: Managed
• Type: Boolean
  • true: Claude Code never runs the marketplace-declared command, doesn't install or update command-sourced plugins, and stops loading the ones already installed
  • false: Claude Code allows command-sourced plugins explicitly
• Default: unset, so Claude Code follows allowManagedHooksOnly: an organization that restricts hook execution to managed settings gets command sources disabled too

{
  "disableCommandPluginSources": true
}

Requires Claude Code v2.1.229 or later.

pluginSuggestionMarketplaces

Name the marketplaces whose plugins can appear as contextual install suggestions, in spinner tips and pinned at the top of the /plugin Discover tab. The built-in first-party frontend-design tip is unaffected. Suggestions come from each plugin's relevance declaration in its marketplace entry.

• Scope: Managed
• Type: array of marketplace names
• Default: unset, so no marketplace-declared suggestions surface

{
  "pluginSuggestionMarketplaces": ["acme-corp-plugins"]
}

A name takes effect only when the marketplace is registered on the machine and its registered source is also declared in the same managed settings, either as the extraKnownMarketplaces entry for that name or as an entry of strictKnownMarketplaces. Claude Code ignores a marketplace registered from a different source under an allowlisted name. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source. See Suggest plugins by context.

pluginTrustMessage

Add your organization's own text to the plugin trust warning Claude Code shows before installation, for example to confirm that plugins from your internal marketplace are vetted.

• Scope: Managed
• Type: string
• Default: unset, so Claude Code shows the standard warning alone

{
  "pluginTrustMessage": "All plugins from our marketplace are approved by IT"
}

strictKnownMarketplaces

Restrict which plugin marketplace sources people in your organization can add and install plugins from. Claude Code enforces the allowlist on marketplace add and on plugin install, update, refresh, and auto-update, before any network or filesystem operation, so a marketplace someone added before you set the policy can't be used to fetch plugins once its source no longer matches. Blocked users see an error naming the managed policy.

• Scope: Managed
• Type: array of marketplace source objects; see Allowed source types
• Default: unset, so users can add any marketplace. An empty array is a complete lockdown that blocks every marketplace source, including the official Anthropic marketplace

This example allows two GitHub repositories, one pinned to the v2.0 ref, and one hosted marketplace.json URL:

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

You can also write this key as allowedMarketplaces; Marketplace key aliases describes how Claude Code treats the alias and which version accepts it. This key is a policy gate: it controls what users may add but registers nothing. To restrict and pre-register in one file, see Combine with extraKnownMarketplaces. For the user-facing view, see Managed marketplace restrictions.

Allowed source types

Each entry below shows one allowlist entry per source type and the fields it accepts. Most types match exactly; hostPattern and pathPattern match by regex, and github entries can use an owner wildcard.

Source	Example entry	Fields
github	\{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" \}	repo required; ref is a branch or tag; path is a subdirectory
git	\{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git", "ref": "production" \}	url required; ref and path as for github
url	\{ "source": "url", "url": "https://plugins.example.com/marketplace.json", "headers": \{ "Authorization": "Bearer ${TOKEN}" } }	url required; headers adds HTTP headers for authenticated access
npm	{ "source": "npm", "package": "@acme-corp/claude-plugins" }	package required, the npm package that contains marketplace.json
file	{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }	path required, the absolute path to a marketplace.json file
directory	{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }	path required, the absolute path to a directory containing .claude-plugin/marketplace.json
hostPattern	{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" \}	hostPattern required, a regex matched against the marketplace host
pathPattern	\{ "source": "pathPattern", "pathPattern": "^/opt/approved/" \}	pathPattern required, a regex matched against the path of file and directory sources
skills-dir	\{ "source": "skills-dir" \}	No fields. Opts the ~/.claude/skills/ plugin scan back in

Three source types carry rules beyond the table:

• url: a URL marketplace downloads only the marketplace.json file, and Claude Code doesn't fetch plugin files by relative path from that server, so its plugins must use a plugin source other than a relative path, such as an archive URL, which can be on the same host. For plugins with relative paths, use a Git-based marketplace instead. See Plugins with relative paths fail in URL-based marketplaces.

• hostPattern: use it to allow every marketplace on an internal GitHub Enterprise or GitLab server without listing each repository. Claude Code matches github sources against github.com, takes the hostname from url sources, and takes it from git sources depending on the git URL's form:

  • A URL with a scheme, such as https:// or ssh://: the hostname in the URL.
  • An SSH address without a scheme, in git's user@host:path form, such as git@git.example.com:tools/plugins.git: the host between @ and :, which is the host git connects to.
  • Any other form without a scheme: no host, so no strictKnownMarketplaces hostPattern entry matches it. For a blockedMarketplaces hostPattern, Claude Code takes a host from a wider set of forms, so a blocklist entry can still match such a form. Before v2.1.234, a strictKnownMarketplaces hostPattern also matched some forms that git doesn't treat as SSH addresses.

  file and directory sources have no host and never match a hostPattern entry.

• pathPattern: use it to allow filesystem marketplaces alongside hostPattern entries for network sources. ".*" allows every local path; a narrower pattern such as "^/opt/approved/" restricts to a directory.

Any allowlist, even an empty one, also stops Claude Code loading @skills-dir plugins from ~/.claude/skills/. Add the \{ "source": "skills-dir" \} entry to keep loading them; the entry has no meaning outside this key and blockedMarketplaces.

Owner wildcards

A github entry whose repo value is "<owner>/*" matches every repository under that GitHub owner. Owner wildcards require Claude Code v2.1.223 or later and work only in strictKnownMarketplaces and blockedMarketplaces. Everywhere else a github source appears, such as extraKnownMarketplaces or /plugin marketplace add, the repo value must name a single repository. Before v2.1.223, Claude Code compared the entry literally, so an allowlist entry matched no repository and a blocklist entry blocked nothing; single-repository entries are enforced on every version.

This entry allows any marketplace repository in the acme-corp organization:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/*" }
  ]
}

Only the whole repository-name position can be a wildcard. Claude Code compares entries such as *, */plugins, or acme-corp/tools-* literally, so they match no repository.

The matching rules differ between the two settings:

Rule	strictKnownMarketplaces	blockedMarketplaces
Matching source spellings	owner/repo form only. A git URL that clones the same repository doesn't match	Any spelling, including git URLs that resolve to the same github.com repository
Owner case	Case-sensitive, like exact-entry matching	Case-insensitive
ref	Follows the exact-entry rules: an entry with a ref matches only sources with that exact ref, and an entry without one matches only sources that don't specify a ref	An entry without a ref blocks all refs of the repositories it matches
path	Looser than the exact-entry rules: an entry with a path requires that exact value, while an entry without one matches any path inside the repository	An entry without a path blocks all paths of the repositories it matches

Exact matching

For every source type except owner-wildcard github entries and the regex-matched hostPattern and pathPattern entries, Claude Code allows a user's addition only when the marketplace source matches an entry exactly. For the git-based sources github and git, exact matching includes the optional fields:

• The repo or url must match exactly
• The ref field must match exactly, or both must be undefined
• The path field must match exactly, or both must be undefined

For example, Claude Code treats each pair below as two different sources:

• \{ "source": "github", "repo": "acme-corp/plugins" \} and \{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" \}
• \{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" \} and \{ "source": "github", "repo": "acme-corp/plugins" \}

Allow only the official marketplace

To allow the official Anthropic marketplace and nothing else, list its repository:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" }
  ]
}

With this entry, Claude Code keeps an already-registered official marketplace available and, on a fresh machine, registers the marketplace automatically the first time you start Claude Code interactively. Automatic registration most commonly misses:

• Non-interactive environments that run before the machine's first interactive launch.
• Machines where Claude Code already ran interactively under a policy that blocked the marketplace, such as the empty-array lockdown. Claude Code records the blocked attempt and doesn't retry after the policy changes.

On these machines, add the marketplace to extraKnownMarketplaces in the same managed-settings.json so Claude Code registers it automatically, or run claude plugin marketplace add anthropics/claude-plugins-official.

Combine with extraKnownMarketplaces

The two keys do different jobs. This table compares them:

Aspect	strictKnownMarketplaces	extraKnownMarketplaces
Purpose	Organizational policy enforcement	Team convenience
Settings file	Managed settings only	Any settings file
Behavior	Blocks non-allowlisted additions	Registers missing marketplaces
When enforced	Before network and filesystem operations	Immediately from user or managed settings; after the workspace trust dialog for a repository's files
Can be overridden	No, highest precedence	Yes, by higher-precedence settings
Source format	Direct source object	Named marketplace with a nested source object

To both restrict and pre-register a marketplace for all users, set both in managed-settings.json:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

With only strictKnownMarketplaces set, users can still add an allowed marketplace themselves with /plugin marketplace add. The official Anthropic marketplace is the only one Claude Code registers automatically, and only when the allowlist allows it. Allow only the official marketplace lists the machines it misses.

strictPluginOnlyCustomization

Block skills, agents, hooks, and MCP servers from user and project sources, so they can come only from plugins or managed settings. Combine it with strictKnownMarketplaces to control the full customization supply chain: the marketplace allowlist controls which plugins users can install.

• Scope: Managed
• Type: true to lock all four kinds of customization, or an array naming the kinds to lock, from "skills", "agents", "hooks", and "mcp"
• Default: unset, so nothing is locked

This example locks skills and hooks and leaves agents and MCP servers unlocked:

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

The four sub-key entries below list what each surface blocks and what still loads. Claude Code ignores surface names it doesn't recognize rather than failing the settings file, so you can add new surface names before every client has updated.

strictPluginOnlyCustomization.skills

Lock the skills surface. Claude Code stops loading skills from ~/.claude/skills/ and .claude/skills/, custom commands from ~/.claude/commands/ and .claude/commands/, skills under --add-dir directories, and skills synced from your claude.ai account, and keeps loading plugin skills, bundled skills, and skills in the managed policy directory.

• Scope: Managed
• Type: the string "skills" in the strictPluginOnlyCustomization array
• Default: not locked

{
  "strictPluginOnlyCustomization": ["skills"]
}

strictPluginOnlyCustomization.agents

Lock the agents surface. Claude Code stops loading agents from ~/.claude/agents/ and .claude/agents/, and keeps loading plugin agents, built-in agents, and agents in the managed policy directory.

• Scope: Managed
• Type: the string "agents" in the strictPluginOnlyCustomization array
• Default: not locked

{
  "strictPluginOnlyCustomization": ["agents"]
}

strictPluginOnlyCustomization.hooks

Lock the hooks surface. Claude Code stops running hooks from user, project, and local settings.json, and keeps running plugin hooks and hooks in managed settings.

• Scope: Managed
• Type: the string "hooks" in the strictPluginOnlyCustomization array
• Default: not locked

{
  "strictPluginOnlyCustomization": ["hooks"]
}

strictPluginOnlyCustomization.mcp

Lock the mcp surface. Claude Code stops loading MCP servers from ~/.claude.json and .mcp.json, and keeps loading plugin MCP servers, managed-mcp.json servers, and servers from managedMcpServers.

• Scope: Managed
• Type: the string "mcp" in the strictPluginOnlyCustomization array
• Default: not locked

{
  "strictPluginOnlyCustomization": ["mcp"]
}

enabledPlugins

Turn individual plugins on or off, keyed by plugin-name@marketplace-name. A plugin with no entry at any scope falls back to its defaultEnabled value. When you enable or disable a plugin with /plugin or claude plugin enable, Claude Code writes this key for you.

• Scope: Any file
• Type: object mapping plugin-name@marketplace-name to a Boolean
• Default: unset, so each plugin follows its defaultEnabled value

This example enables two plugins from the team-tools marketplace and disables one from personal:

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

Each scope serves a different purpose:

• User settings: your personal plugin preferences
• Project settings: plugins shared with everyone in the repository
• Local settings: per-machine overrides, gitignored when Claude Code saves a setting there
• Managed settings: organization-wide policy. A plugin set to false here is blocked from installation at every scope and hidden from the marketplace

Project settings take precedence over user settings, so setting a plugin to false in ~/.claude/settings.json doesn't disable a plugin that the project's .claude/settings.json enables. To opt out of a project-enabled plugin on your machine, set it to false in .claude/settings.local.json instead. Plugins force-enabled by managed settings can't be disabled this way, since managed settings override local settings.

Enabling a plugin from an external source such as a GitHub repository or npm package in a project's .claude/settings.json doesn't install it for other people. On every path that loads plugins, Claude Code reports the plugin as not installed until each user installs it themselves.

extraKnownMarketplaces

Register additional plugin marketplaces by name, so that people who open the repository, or everyone your managed settings reach, get the marketplace without adding it themselves. Claude Code registers each marketplace it doesn't already know. Whether a plugin that enabledPlugins names from it installs depends on the plugin's source and which file enables it; that entry has the rules.

• Scope: Any file. Claude Code honors entries in a repository's .claude/settings.json or .claude/settings.local.json only after you accept the workspace trust dialog for that folder; in a folder you haven't trusted, including a -p run there, it ignores them without a message.
• Type: object mapping a marketplace name to an object with a source object and an optional autoUpdate Boolean
• Default: unset

This example registers a GitHub marketplace and a marketplace from a self-hosted git URL:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

What runs before you trust a folder compares the trust gate with the other content a repository can supply. You can also write this key as additionalMarketplaces; see Marketplace key aliases.

Set "autoUpdate": true alongside source to make Claude Code refresh that marketplace and update its installed plugins in the background after startup. When omitted, claude-plugins-official and most other official Anthropic marketplaces default to true, and third-party marketplaces default to false. See Configure auto-updates.

When more than one settings file defines a marketplace entry under the same name, Claude Code uses the entry from the highest-precedence file whole. That entry replaces the lower-precedence entry and inherits none of its fields, so a redefinition can't combine one file's source.headers credential with a URL another file controls. Before v2.1.228, Claude Code merged same-name entries field by field, so an entry in a higher-precedence file could inherit fields it didn't set, including another file's headers.

Marketplace source types

The source object takes one of these forms:

• github: a GitHub repository, with repo
• git: any git URL, with url
• url: a direct URL to a marketplace.json file, with url and optional headers and headersHelper for authenticated access. headersHelper names a command that prints headers whose values are too short-lived to list in headers, and requires Claude Code v2.1.238 or later
• file: a local path to a marketplace.json file, with path
• directory: a local filesystem path, with path, for development only
• settings: an inline marketplace declared directly in the settings file without a hosted repository, with name and plugins

The git source type works with any git hosting service, including self-hosted GitLab and Bitbucket. Claude Code clones the repository with the same authentication that git clone would use on that machine: configured credential helpers or SSH keys. A provider token such as GITHUB_TOKEN takes effect only through a credential helper that reads it. See Private repositories for setup details.

For github and git sources, set "skipLfs": true inside the source object, alongside repo or url, to skip Git LFS downloads when Claude Code clones or updates the marketplace repository. LFS pointer files remain as pointers instead of downloading their content. Use this when the repository contains large LFS objects unrelated to plugin content.

For a url source, set headersHelper inside the source object when the credential in headers expires and a command has to produce a fresh one. Requires Claude Code v2.1.238 or later. For what the command must print and where Claude Code runs it, see Write the headersHelper command, and for the cases where Claude Code doesn't run it, see When Claude Code skips a headersHelper command. Once you set headersHelper on an https:// marketplace URL, Claude Code runs the command at two points, reusing one run's output for up to 60 seconds:

• Before each fetch of that marketplace's marketplace.json, including a later refresh. Claude Code sends the printed headers with that fetch.
• Before each plugin archive download on the marketplace URL's origin, meaning the same scheme, host, and port. Claude Code sends the output with that download, and no other download gets the headers.

Claude Code ignores any headersHelper set in the .claude/settings.json or .claude/settings.local.json of a directory you add with --add-dir, on a url source and on an inline plugin entry alike, and sends only the fixed headers set in that file. How users accept a headersHelper command covers the other settings files.

Plugins listed in a settings source must reference external sources such as GitHub or npm, and the name must match the marketplace key. You still enable each plugin separately in enabledPlugins. This example declares one plugin inline:

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

A plugin entry under source: 'settings' whose own source is an archive can set headers for the archive download. If the value you would put in headers is short-lived, such as a token your registry mints on request, set a headersHelper command instead. An entry may set both. Both fields require Claude Code v2.1.238 or later.

Claude Code sends the entry's headers, and whatever the command prints, with that plugin's archive download and with no other download. Claude Code runs the command only when a user installs or updates that one plugin by itself. Three further rules depend on which file holds the entry:

• strict: unlike an entry in a marketplace's marketplace.json, an entry in settings doesn't need "strict": false, because a settings file carries no manifest fields to inline. See Strict mode.
• Folder trust: for an entry in a project's .claude/settings.json or .claude/settings.local.json, Claude Code runs the command only after the user has also trusted that folder.
• Header filter: Claude Code drops request-routing and client-identity header names from an entry in a project's .claude/settings.json or .claude/settings.local.json, because a repository can supply those files. Claude Code applies the same filter to a catalog entry and to an entry in an --add-dir directory's settings, and no filter to an entry in your user settings, a --settings file, or managed settings.

Marketplace key aliases

On Claude Code v2.1.232 or later, you can write extraKnownMarketplaces as additionalMarketplaces and strictKnownMarketplaces as allowedMarketplaces. Claude Code treats each alias as follows:

• Earlier versions ignore the alias, so keep the canonical spelling in a file that older versions also read, such as a managed settings file for a fleet with mixed Claude Code versions.
• In any settings file that accepts the canonical key, Claude Code reads the alias exactly as it reads the canonical key.
• Claude Code may rewrite additionalMarketplaces to extraKnownMarketplaces when it updates the file.
• If you set both spellings in one file, Claude Code uses the canonical value and ignores the alias.

pluginConfigs

Store the non-sensitive answers you give a plugin's userConfig configuration dialog, keyed by plugin ID. Claude Code writes this key to your user settings when you fill in the dialog, so you don't need to edit it by hand. Claude Code stores sensitive options in the macOS Keychain instead, falling back to ~/.claude/.credentials.json when the Keychain rejects the write; on platforms without a supported keychain, it stores them in ~/.claude/.credentials.json.

• Scope: User or managed
• Type: object mapping a plugin ID to an object with an options field, mapping each option name to a string, number, Boolean, or array of strings, and an optional mcpServers field holding per-server user configuration values in the same shape
• Default: unset

This example stores the api_endpoint option for the deployer plugin from acme-tools:

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

Claude Code ignores project and local entries because it substitutes these values into plugin hook, MCP, and LSP configurations, and a cloned repository must not be able to supply them. Before v2.1.207, project and local settings were also read.