Claude Code settings reference

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"
  }
}

"name-only" lists the skill to the model without its description, "user-invocable-only" hides it from the model but keeps /name typable, and "off" hides it from both. Overrides don't apply to plugin skills, which you manage through /plugin.

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
• 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.

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:

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:

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 and managed-mcp.json servers.

• 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. Requires Claude Code v2.1.153 or later.

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. Sensitive options go to the macOS Keychain instead, or to ~/.claude/.credentials.json on platforms without a supported keychain.

• 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.

MCP

Control which MCP servers Claude Code connects to and which an organization allows. See Connect to external tools with MCP and Managed MCP configuration.

allowAllClaudeAiMcps

Load the claude.ai connectors Claude Code fetches itself alongside a deployed managed-mcp.json. Without this key, managed-mcp.json takes exclusive control of MCP servers and suppresses those connectors.

• Scope: Managed. Users can't re-enable connectors that exclusive control suppressed.
• Type: Boolean
  • true: Claude Code loads the claude.ai connectors alongside a deployed managed-mcp.json
  • false: a deployed managed-mcp.json takes exclusive control of MCP servers and suppresses claude.ai connectors
• Default: false, so a deployed managed-mcp.json suppresses claude.ai connectors

{
  "allowAllClaudeAiMcps": true
}

allowedMcpServers and deniedMcpServers still apply to the connectors this key loads. Connectors delivered to cloud sessions stay suppressed. See Allow claude.ai connectors alongside the managed set.

allowedMcpServers

Allowlist the MCP servers people can use. Claude Code blocks any server that doesn't match an entry, whichever settings file or .mcp.json defined it, including servers from managed-mcp.json. Built-in servers such as Claude in Chrome, IDE-provided servers, and servers the CLI itself configures are exempt from the allowlist; the denylist still applies to them.

• Scope: Any file. Entries from every file merge into one allowlist unless allowManagedMcpServersOnly is set. Deploy it in managed settings to enforce it.
• Type: array of objects, each with exactly one key: serverName, a string limited to letters, numbers, hyphens, and underscores; serverCommand, an array of the command and its arguments matched exactly; or serverUrl, a URL pattern with * wildcards
• Default: unset, so every server is allowed; an empty array blocks every server

This example allows only the stdio server that the listed npx command starts:

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] }
  ]
}

A deniedMcpServers entry takes precedence, so a server on both lists is blocked. Once the list contains any serverCommand entry, a stdio server must match a serverCommand entry, and once it contains any serverUrl entry, a remote server must match a serverUrl entry: a serverName match no longer admits that kind of server. See Policy-based control with allowlists and denylists.

allowManagedMcpServersOnly

Make the managed allowlist the only one that applies. Claude Code then reads allowedMcpServers from managed settings alone and ignores allowlists in user, project, and local settings; deniedMcpServers still merges from every file, so users can still block servers for themselves. Administrators set it so a user's own settings can't broaden what the managed allowlist permits.

• Scope: Managed
• Type: Boolean
  • true: Claude Code reads allowedMcpServers from managed settings alone and ignores allowlists in user, project, and local settings
  • false: allowlists from every settings file merge
• Default: false, so allowlists from every settings file merge

This example locks the allowlist to managed settings and allows only the server named github:

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverName": "github" }
  ]
}

Users can still add MCP servers of their own; only servers that match the managed allowlist load. See Restrict the allowlist to managed settings only.

deniedMcpServers

Block specific MCP servers. Claude Code refuses to load a matching server in every scope, including servers from managed-mcp.json and claude.ai connectors.

• Scope: Any file. Entries from every file merge into one denylist, and allowManagedMcpServersOnly doesn't change that. Deploy it in managed settings to enforce it.
• Type: array of objects, each with exactly one key: serverName, any non-empty string, so a claude.ai connector's display name such as "claude.ai Slack" works; serverCommand, an array of the command and its arguments matched exactly; or serverUrl, a URL pattern with * wildcards
• Default: unset, so no server is blocked; an empty array also blocks nothing

{
  "deniedMcpServers": [
    { "serverName": "filesystem" }
  ]
}

The denylist takes precedence over allowedMcpServers, so a server on both lists is blocked. See Policy-based control with allowlists and denylists.

disableClaudeAiConnectors

Turn off claude.ai MCP connectors so Claude Code neither fetches nor connects them. A true in any settings file applies: a checked-in project .claude/settings.json can opt a repository out of cloud connectors, but a project-level false can't override a user- or managed-level true. Requires Claude Code v2.1.182 or later.

• Scope: Any file
• Type: Boolean
  • true: Claude Code neither fetches nor connects claude.ai MCP connectors
  • false: the same as unset; Claude Code fetches your connectors unless another settings file or ENABLE_CLAUDEAI_MCP_SERVERS turns them off
• Default: false, so Claude Code fetches your connectors
• Per-session overrides: ENABLE_CLAUDEAI_MCP_SERVERS set to false turns connectors off for one session; whichever of the two turns them off, the other can't turn them back on

{
  "disableClaudeAiConnectors": true
}

Servers you pass explicitly with --mcp-config are unaffected. To block individual connectors instead of all of them, use deniedMcpServers. See Disable claude.ai connectors. Requires Claude Code v2.1.182 or later.

disabledMcpjsonServers

Reject specific servers defined in a project's .mcp.json file so Claude Code never connects them or asks you to approve them. A rejection in any settings file applies, including a project .claude/settings.json checked into the repository.

• Scope: Any file
• Type: array of strings, the server names as they appear in .mcp.json
• Default: unset

{
  "disabledMcpjsonServers": ["filesystem"]
}

Claude Code writes this key to .claude/settings.local.json when you reject a server in the approval dialog. claude mcp get <name> shows a rejected server as ✘ Rejected (see disabledMcpjsonServers in settings). Rejection takes precedence over enabledMcpjsonServers and enableAllProjectMcpServers.

enableAllProjectMcpServers

Approve every MCP server defined in project .mcp.json files without a prompt. Claude Code writes this key to .claude/settings.local.json when you choose to approve all servers in the approval dialog.

• Scope: Any file. In a folder whose trust dialog you haven't accepted, Claude Code honors it from user settings, managed settings, and --settings and ignores it in the shared project file, both in the session and for claude mcp list and claude mcp get; Project server approvals and workspace trust says when an untracked .claude/settings.local.json counts too.
• Type: Boolean
  • true: Claude Code approves every MCP server defined in project .mcp.json files without a prompt
  • false: Claude Code asks you to approve each server. In a trusted folder, a false in a higher-precedence file overrides a true in a lower one; in a folder you haven't trusted, a true in any honored file is enough
• Default: unset, so Claude Code asks you to approve each server

{
  "enableAllProjectMcpServers": true
}

A disabledMcpjsonServers entry still rejects a server.

enabledMcpjsonServers

Approve specific servers defined in project .mcp.json files so Claude Code connects them without asking. Claude Code writes this key to .claude/settings.local.json when you approve a server in the approval dialog.

• Scope: Any file. In a folder whose trust dialog you haven't accepted, Claude Code honors it from user settings, managed settings, and --settings and ignores it in the shared project file, both in the session and for claude mcp list and claude mcp get; Project server approvals and workspace trust says when an untracked .claude/settings.local.json counts too.
• Type: array of strings, the server names as they appear in .mcp.json
• Default: unset

This example approves the memory and github servers from the project's .mcp.json:

{
  "enabledMcpjsonServers": ["memory", "github"]
}

A disabledMcpjsonServers entry still rejects a server.

Agents, sessions, and worktrees

Set the default agent, control teammates and cross-session messaging, and configure worktrees. See Subagents and Worktrees.

agent

Run the main thread as a named subagent, so Claude Code applies that subagent's system prompt, tool restrictions, and model to your session. The same key sets the default agent for sessions you dispatch from claude agents.

• Scope: Any file
• Type: string, the name of a built-in or custom agent
• Default: unset, so the main thread runs as Claude Code's default agent
• Per-session overrides: --agent takes precedence over this key for one session

{
  "agent": "code-reviewer"
}

A plugin's own settings.json can also supply this key; see Ship default settings with your plugin.

crossSessionInbound

Choose what this session does with messages arriving from your other Claude Code sessions. When no value applies, Claude Code decides per message from the two sessions' permission-mode classes. Requires Claude Code v2.1.224 or later.

• Scope: Any file. A project or local value applies only when it's stricter than the value managed settings, the --settings flag, or user settings give.
• Type: string, one of:
  • "accept": Claude Code delivers the message to Claude
  • "hold": Claude Code shows a notice for the message without delivering it
  • "refuse": Claude Code drops the message
• Default: unset, so Claude Code decides per message

{
  "crossSessionInbound": "hold"
}

Claude Code reads managed settings first, then the --settings flag, then user settings, and applies the first value found. refuse is stricter than hold, and hold is stricter than accept. When none of the trusted sources sets a value, a project or local hold or refuse still applies, replacing the per-message default. In sessions with cross-session messaging, this key appears in /config as Messages from your other sessions, which writes it to user settings; the row requires Claude Code v2.1.232 or later, and Claude Code hides it while the --settings flag or managed settings set the key.

disableAgentView

Turn off background agents and agent view: claude agents, --bg, /background, and the on-demand supervisor. Set it in managed settings to enforce it for an organization.

• Scope: Any file
• Type: Boolean
  • true: Claude Code turns off claude agents, --bg, /background, and the on-demand supervisor
  • false: agent view is available
• Default: unset, so agent view is available
• Per-session overrides: CLAUDE_CODE_DISABLE_AGENT_VIEW turns agent view off for one session; whichever of the two turns it off, the other can't turn it back on

{
  "disableAgentView": true
}

isolatePeerMachines

Require your explicit approval before Claude's SendMessage reaches one of your sessions beyond this machine; see Require approval for cross-machine messages. The approval prompt appears even in bypassPermissions mode.

• Scope: Any file. A true from any scope applies, so a checked-in project file can turn the requirement on but not off.
• Type: Boolean
  • true: Claude Code asks for your approval before Claude's SendMessage reaches one of your sessions beyond this machine
  • false: cross-machine messages don't prompt
• Default: unset, so cross-machine messages don't prompt

{
  "isolatePeerMachines": true
}

The cross-machine SendMessage approval requires Claude Code v2.1.224 or later.

processWrapper

On macOS and Linux, place a corporate launcher command in front of the background processes Claude Code starts. Claude Code runs the launcher with its own command line appended, so the launcher must exec into Claude Code; see Run Claude Code behind a corporate launcher for the launcher contract. Requires Claude Code v2.1.210 or later.

• Scope: User or managed
• Type: string, the launcher command as an argv prefix, such as an absolute path with optional arguments
• Default: unset, so background processes start unwrapped
• Per-session overrides: CLAUDE_CODE_PROCESS_WRAPPER takes precedence over this key for one session

{
  "processWrapper": "/opt/corp/launcher --profile claude"
}

Claude Code ignores the launcher on Windows and starts every process unwrapped. Requires Claude Code v2.1.210 or later.

teammateMode

Choose where Claude Code shows agent team teammates: inside your main terminal pane, or in split panes when your terminal supports them. See Choose a display mode.

• Scope: Any file. Claude Code also reads a value left in ~/.claude.json by older versions.
• Type: string, one of:
  • "in-process": teammates run inside your main terminal pane
  • "auto": split panes when you're running inside tmux, or inside iTerm2 with it2 on your PATH or tmux installed; in-process otherwise
  • "tmux": split panes using tmux or iTerm2, detected from your terminal
  • "iterm2": iTerm2 native split panes through the it2 CLI, in Claude Code v2.1.186 or later
• Default: "in-process"
• Per-session overrides: --teammate-mode takes precedence over this key for one session

{
  "teammateMode": "auto"
}

Before v2.1.179, the default was auto. The iterm2 value requires Claude Code v2.1.186 or later.

{
  "worktree": {
    "baseRef": "head",
    "symlinkDirectories": ["node_modules"]
  }
}

{
  "worktree": {
    "baseRef": "head"
  }
}

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

{
  "worktree": {
    "bgIsolation": "none"
  }
}

{
  "agentPushNotifEnabled": true
}

{
  "awaySummaryEnabled": false
}

{
  "disableArtifact": true
}

{
  "disableDeepLinkRegistration": "disable"
}

{
  "disableDesktopLocalSessions": true
}

{
  "disableRemoteControl": true
}

{
  "enableArtifact": false
}

{
  "inputNeededNotifEnabled": true
}

{
  "preferredNotifChannel": "terminal_bell"
}

{
  "remote": {
    "defaultEnvironmentId": "env_0123abcd"
  }
}

{
  "remoteControlAtStartup": true
}

{
  "sshConfigs": [
    {
      "id": "dev-vm",
      "name": "Dev VM",
      "sshHost": "user@dev.example.com"
    }
  ]
}

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

{
  "apiKeyHelper": "/bin/generate_temp_api_key.sh"
}

{
  "awsAuthRefresh": "aws sso login --profile myprofile"
}

{
  "awsCredentialExport": "/bin/generate_aws_grant.sh"
}

{
  "forceLoginMethod": "claudeai"
}

{
  "forceLoginGatewayUrl": "https://claude-gateway.example.com"
}

{
  "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]
}

{
  "gcpAuthRefresh": "gcloud auth application-default login"
}

{
  "otelHeadersHelper": "/bin/generate_otel_headers.sh"
}