Claude Code settings

Configure Claude Code with global and project-level settings, and environment variables.

Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the /config command in an interactive session, which opens a tabbed Settings interface where you can view status information and modify configuration options. From v2.1.181, you can change a single option without opening the interface by passing key=value to /config, for example /config verbose=true.

Configuration scopes

Claude Code uses a scope system to determine where configurations apply and who they're shared with. Understanding scopes helps you decide how to configure Claude Code for personal use, team collaboration, or enterprise deployment.

Available scopes

When to use each scope

Managed scope is for:

• Security policies that must be enforced organization-wide
• Compliance requirements that can't be overridden
• Standardized configurations deployed by IT/DevOps

User scope is best for:

• Personal preferences you want everywhere (themes, editor settings)
• Tools and plugins you use across all projects
• API keys and authentication (stored securely)

Project scope is best for:

• Team-shared settings (permissions, hooks, MCP servers)
• Plugins the whole team should have
• Standardizing tooling across collaborators

Local scope is best for:

• Personal overrides for a specific project
• Testing configurations before sharing with the team
• Machine-specific settings that won't work for others

How scopes interact

When the same setting appears in multiple scopes, Claude Code applies them in priority order:

1. Managed (highest): can't be overridden by any other scope, apart from the exceptions to managed settings precedence
2. Command line arguments: temporary session overrides
3. Local: overrides project and user settings
4. Project: overrides user settings
5. User (lowest): applies when nothing else specifies the setting

For example, if your user settings set spinnerTipsEnabled to true and project settings set it to false, the project value applies. Permission rules merge across scopes instead, and a few security-sensitive keys are exceptions. See Settings precedence.

What uses scopes

Scopes apply to many Claude Code features:

On Windows, paths shown as ~/.claude resolve to %USERPROFILE%\.claude.

Settings files

The settings.json file is the official mechanism for configuring Claude Code through hierarchical settings:

• User settings are defined in ~/.claude/settings.json and apply to all projects.

• Project settings are saved in your project directory:

  • .claude/settings.json for settings that are checked into source control and shared with your team

  • .claude/settings.local.json for settings that are not checked in, useful for personal preferences and experimentation. When Claude Code saves a setting to this file in a repository that doesn't already ignore it, Claude Code adds **/.claude/settings.local.json to your global git excludes file. That excludes file is core.excludesFile from your global git config when it's set to an absolute or ~-prefixed path, otherwise $XDG_CONFIG_HOME/git/ignore, or ~/.config/git/ignore. If you create the file by hand or have Claude write it with the Write tool, add it to your gitignore yourself.

    Claude Code reads and writes this file at the root of the git repository, resolved through worktrees to the main checkout, so one file covers sessions started in any subdirectory or worktree of the repository. The file stays in the directory you start Claude Code from in three cases: outside a git repository, when the repository root is your home directory, and in Agent SDK sessions.

    Claude Code also saves permanent "don't ask again" permission approvals, such as Bash command approvals, to this file.

    Because this file is yours rather than the repository's, its permission allow rules take effect without the workspace trust step that .claude/settings.json allow rules require. If the repository supplies the file, for example by committing it, workspace trust still applies.

• Managed settings: For organizations that need centralized control, Claude Code supports multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings:

  • Server-managed settings: delivered remotely at sign-in, either from Anthropic's servers via the claude.ai admin console or from a self-hosted Claude apps gateway. See server-managed settings.

  • MDM/OS-level policies: delivered through native device management on macOS and Windows:

    • macOS: com.anthropic.claudecode managed preferences domain. The plist's top-level keys mirror managed-settings.json, with nested settings as dictionaries and arrays as plist arrays. Deploy via configuration profiles in Jamf, Iru (Kandji), or similar MDM tools.
    • Windows: HKLM\SOFTWARE\Policies\ClaudeCode registry key with a Settings value (REG_SZ or REG_EXPAND_SZ) containing JSON (deployed via Group Policy or Intune)
    • Windows (user-level): HKCU\SOFTWARE\Policies\ClaudeCode (lowest policy priority, only used when no admin-level source exists)

  • File-based: managed-settings.json and managed-mcp.json deployed to system directories:

    • macOS: /Library/Application Support/ClaudeCode/
    • Linux and WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\

    File-based managed settings also support a drop-in directory at managed-settings.d/ in the same system directory alongside managed-settings.json. This lets separate teams deploy independent policy fragments without coordinating edits to a single file.

    Following the systemd convention, Claude Code merges managed-settings.json first as the base, then sorts all *.json files in the drop-in directory alphabetically and merges them on top. For scalar values, Claude Code lets later files override earlier ones; it concatenates and de-duplicates arrays and deep-merges objects. A later file's fallbackModel chain replaces an earlier one instead of merging with it, and a later file's extraKnownMarketplaces entry replaces an earlier file's same-name entry whole. Claude Code ignores hidden files starting with ..

    Use numeric prefixes to control merge order, for example 10-telemetry.json and 20-security.json.

  See managed settings and Managed MCP configuration for details.

  This repository includes starter deployment templates for Jamf, Iru (Kandji), Intune, and Group Policy. Use these as starting points and adjust them to fit your needs.

• Other configuration is stored in ~/.claude.json. This file contains your OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in .mcp.json.

The following example works in any of the settings file locations above. Where you save the file determines where it applies:

• To apply it to all of your projects, save it as ~/.claude/settings.json. This file lives in your home directory rather than in any project, so Claude Code reads it in every session regardless of which project you open.
• To share it with collaborators on one project, save it as .claude/settings.json in that project. Claude Code reads this file from the directory the session runs in, so it applies only to that project, and checking it into source control gives every collaborator the same settings.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

The $schema line in the example above points to the official JSON schema for Claude Code settings. Adding it to your settings.json enables autocomplete and inline validation in VS Code, Cursor, and any other editor that supports JSON schema validation.

The published schema is updated periodically and may not include settings added in the most recent CLI releases, so a validation warning on a recently documented field does not necessarily mean your configuration is invalid.

When edits take effect

Claude Code watches your settings files and reloads them when they change, so edits to most keys apply to the running session without a restart. This includes permissions, hooks, and credential helpers like apiKeyHelper. The reload covers user, project, local, and managed settings, and the ConfigChange hook fires for each detected change.

A few keys are read once at session start and apply on the next restart instead:

• model: use /model to switch mid-session
• outputStyle: part of the system prompt, which is rebuilt on /clear or restart

Invalid entries in managed settings

Managed settings parse tolerantly. When a managed configuration contains an entry that fails schema validation, Claude Code strips that entry, records a warning, and enforces every remaining valid policy. A single typo cannot disable the rest of your organization's policy. Run /doctor to list stripped entries with their source file and field.

This behavior is consistent across all three delivery mechanisms: server-managed settings, plist and registry policies deployed through MDM, and managed-settings.json files. Requires Claude Code v2.1.169 or later.

Security-enforcement fields are handled per field instead of being stripped wholesale when they are present but invalid:

requiredMinimumVersion and requiredMaximumVersion fail open by design: an invalid value is stripped rather than enforced, so a bad policy push cannot prevent Claude Code from starting.

Validation errors surface in three places:

• Interactive sessions show a dialog at startup listing the invalid entries.
• Headless runs with -p print a summary to stderr.
• claude doctor lists each invalid entry with its source and field.

Validate policy changes by running claude doctor on a test machine before deploying them fleet-wide.

This tolerance applies only to managed settings. User, project, and local settings files remain strict: a file that fails validation is rejected as a whole and reported.

Available settings

settings.json supports a number of options:

Global config settings

These settings are stored in ~/.claude.json rather than settings.json. If you add these keys to settings.json, Claude Code silently ignores them at startup, so double-check the table below for which file each key belongs in.

Worktree settings

Configure how --worktree creates and manages git worktrees.

To copy gitignored files like .env into new worktrees, use a .worktreeinclude file in your project root instead of a setting.

Permission settings

Permission rule syntax

Permission rules follow the format Tool or Tool(specifier). Rules are evaluated in order: deny rules first, then ask, then allow. The first match determines the outcome regardless of rule specificity. See the permission rule evaluation order for details.

Quick examples:

For the complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP, and Agent rules, and security limitations of Bash patterns, see Permission rule syntax.

Sandbox settings

Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See Sandboxing for details.

Sandbox path prefixes

Paths in filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead, filesystem.allowRead, and credentials.files support these prefixes:

The older //path prefix for absolute paths still works. If you previously used single-slash /path expecting project-relative resolution, switch to ./path.

Claude Code strips a trailing slash from a directory path, so ~/.aws and ~/.aws/ match the same directory. Before v2.1.224, Claude Code passed the trailing slash through to the sandbox, and Claude could still read or write paths under a denyRead or denyWrite entry written with one.

Claude Code also removes a trailing /**, so ~/build/** and ~/build cover the same directory. For the four filesystem lists, whether a wildcard such as * works depends on which list the entry is in and on the platform:

• allowWrite and denyWrite: on macOS, wildcards work. On Linux and WSL2, the sandbox mounts concrete paths, so Claude Code skips an entry that contains *, ?, or [ once the trailing /** is removed, and that entry has no effect. Claude Code adds the paths from your Edit permission rules to these lists, so the same limit applies to them, and the Config tab of /sandbox lists the Edit rules Claude Code skipped.
• denyRead and allowRead: wildcards work on every platform. On Linux and WSL2, Claude Code expands a read entry to the concrete paths it matches, which it doesn't do for the write lists.

This syntax differs from Read and Edit permission rules, which use //path for absolute and /path for project-relative. Sandbox filesystem paths use standard conventions: /tmp/build is an absolute path.

Configuration example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

Filesystem and network restrictions can be configured in two ways that are merged together:

• sandbox.filesystem settings (shown above): Control paths at the OS-level sandbox boundary, or set filesystem.disabled to true to turn that layer off entirely. These restrictions apply to all subprocess commands (e.g., kubectl, terraform, npm), not just Claude's file tools.
• Permission rules: Use Edit allow/deny rules to control Claude's file tool access, Read deny rules to block reads (a Read deny rule also blocks the Edit and Write tools on the matching paths), and WebFetch allow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration.

Attribution settings

Claude Code adds attribution to git commits and pull requests. These are configured separately:

• Commits use git trailers (like Co-Authored-By) by default, which can be customized or disabled
• Pull request descriptions are plain text

Default commit attribution:

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

The model name in the trailer reflects the active model for the session.

Default pull request attribution:

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Example:

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

File suggestion settings

Configure a custom command for @ file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.

Claude Code can skip your custom command without warning and serve @ autocomplete from the built-in file suggestion instead. The Hook configuration section describes the gates.

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

The command runs with the same environment variables as hooks, including CLAUDE_PROJECT_DIR. It receives JSON via stdin with a query field:

{"query": "src/comp"}

Output newline-separated file paths to stdout (currently limited to 15):

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

Example:

#!/bin/bash
query=$(cat | jq -r '.query')
# Replace your-repo-file-index with your own file search command
your-repo-file-index --query "$query" | head -20

Footer link badges

The footerLinksRegexes setting renders extra clickable badges in the footer below the input box. Use it to turn IDs printed by project CLIs, such as review tools and issue trackers, into session links.

Each entry's pattern regex is matched against turn output: tool results, including file contents and fetched pages, and Claude's own responses. {name} placeholders in url and label are filled from named capture groups in the pattern.

The following example renders a badge whenever an issue key like PROJ-1234 appears in turn output. The (?<key>...) named group captures the key, and {key} substitutes it into the URL and label:

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

With this configured, when PROJ-1234 appears in a tool result or in Claude's reply, a PROJ-1234 badge appears in the footer linking to https://issues.example.com/browse/PROJ-1234.

The following constraints apply to each entry:

When a turn completes, Claude Code matches each entry's pattern regex against the turn output on the main thread, so a slow regex blocks the UI until it finishes. Nested quantifiers such as (a+)+$ can take exponentially long against certain inputs and freeze the session, so keep each pattern linear and avoid nesting + or *.

Footer badges render alongside a custom status line when one is configured; neither replaces the other. Use a status line for a script-driven row that computes its own content from session data, and footer badges to turn IDs from the conversation into links without a script.

Hook configuration

These settings control which hooks are allowed to run and what HTTP hooks can access. The allowManagedHooksOnly setting can only be configured in managed settings. The URL and env var allowlists can be set at any settings level and merge across sources.

Behavior when allowManagedHooksOnly is true:

• Managed hooks and SDK hooks are loaded
• Hooks from plugins force-enabled in managed settings enabledPlugins are loaded. This lets administrators distribute vetted hooks through an organization marketplace while blocking everything else. Trust is granted by full plugin@marketplace ID, so a plugin with the same name from a different marketplace stays blocked
• User hooks, project hooks, local hooks, and all other plugin hooks are blocked
• Claude Code also disables plugins with a command source, including plugins force-enabled in managed settings enabledPlugins, unless disableCommandPluginSources is explicitly set to false
• Claude Code also narrows statusLine, fileSuggestion, and subagentStatusLine to managed settings, following the two decisions below

Status line and file suggestion gates: Claude Code makes two decisions for statusLine, fileSuggestion, and subagentStatusLine. It turns the feature off entirely when managed settings set disableAllHooks, or when the folder isn't trusted under the same workspace trust rule as hooks in settings files. It narrows the source to managed settings when allowManagedHooksOnly is set or when disableAllHooks is true outside managed settings after settings precedence applies. Under narrowing, Claude Code runs a managed value if one is deployed; otherwise it skips your value without warning, the status line is disabled, and @ autocomplete falls back to the built-in file suggestion.

Restrict HTTP hook URLs:

Limit which URLs HTTP hooks can target. Supports * as a wildcard for matching. When the array is defined, HTTP hooks targeting non-matching URLs are silently blocked. Hostname matching is case-insensitive and ignores a trailing FQDN dot, matching DNS semantics.

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

Restrict HTTP hook environment variables:

Limit which environment variable names HTTP hooks can interpolate into header values. Each hook's effective allowedEnvVars is the intersection of its own list and this setting.

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

Compute managed settings with a policy helper

The policyHelper setting points at an executable that computes managed settings at startup, so admins can derive policy from device posture, identity, or a remote service instead of a static file. Configure it from MDM or a system managed-settings.json file. Claude Code ignores policyHelper when it appears in any other scope, including user settings, project settings, the HKCU registry hive, and server-managed settings.

The setting accepts these keys:

The helper writes a JSON envelope to stdout. Put the settings under a managedSettings key rather than at the top level, since a bare settings object parses with managedSettings undefined and applies nothing:

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

When the helper emits managedSettings, that object becomes the only managed settings source for the run: Claude Code ignores remote, MDM, and file-based sources, reads the cross-source keys from the helper's output alone, and never merges parent settings. A helper that exits 0 without emitting managedSettings contributes no managed settings, and the other sources apply as usual. When the helper exits non-zero at startup, Claude Code prints the error and refuses to start, so a helper that needs outage resilience should serve from its own cache and exit 0.

Settings precedence

Claude Code reads settings from these levels, highest precedence first. A few security-sensitive keys and one host-integration case don't follow this order, in either direction; Exceptions to managed settings precedence lists them.

1. Managed settings (server-managed, MDM/OS-level policies, or managed settings files)

   • Your organization deploys these through server delivery, MDM configuration profiles, registry policies, or managed settings files
   • No other level overrides them, including command line arguments, apart from the exceptions to managed settings precedence
   • When your organization delivers more than one managed source, precedence within the managed tier determines what Claude Code reads from each

2. Command line arguments

   • Values you pass for one session. JSON you pass with --settings <file-or-json> merges with your settings files by the same rules as the other levels: a key you set here overrides the same key in local, project, or user settings, and a key you omit keeps its lower-level value

3. Local project settings (.claude/settings.local.json)

   • Your personal settings for this project

4. Shared project settings (.claude/settings.json)

   • Settings your team checks into source control

5. User settings (~/.claude/settings.json)

   • Your personal settings for every project

The same order applies whether you run Claude Code from the CLI, the VS Code extension, or a JetBrains IDE. For example, if you set spinnerTipsEnabled to true in your user settings and your team sets it to false in the project's shared settings, the project value applies.

Exceptions to managed settings precedence

For a few security-sensitive keys, Claude Code honors a restrictive value from a scope that otherwise couldn't override managed settings. Find the key in this table to see which value it honors and from where.

A host platform that embeds Claude Code and sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST is also an exception. Claude Code takes the host's model configuration over the model, fallbackModel, and modelOverrides keys from every managed source, and over the model-selection variables in a managed env block, such as ANTHROPIC_MODEL and the ANTHROPIC_DEFAULT_*_MODEL family. A managed availableModels allowlist stays in force unless the host supplies its own.

Precedence within the managed tier

A policyHelper can replace every source in this list; that section says when. Otherwise, apart from the cross-source keys listed after the ranking, Claude Code uses the first of these sources that delivers a non-empty configuration and ignores the rest rather than merging them:

1. Remote settings, delivered from claude.ai as server-managed settings or by a Claude apps gateway
2. MDM or OS-level policies
3. Managed settings files, managed-settings.d/*.json and managed-settings.json merged together
4. The HKCU registry, on Windows only

Claude Code honors a few keys from any admin-controlled managed source, not only the one it selected above. The user-writable HKCU registry source is excluded from these checks. These cross-source keys are:

• The sandbox lock keys sandbox.network.allowManagedDomainsOnly and sandbox.filesystem.allowManagedReadPathsOnly, with their associated allowlists
• allowAllClaudeAiMcps
• The sandbox binary paths sandbox.bwrapPath and sandbox.socatPath
• The sandbox ripgrep binary, sandbox.ripgrep
• forceRemoteSettingsRefresh
• env, which Claude Code merges per variable across the admin-controlled sources: each variable comes from the highest-priority source that defines it, so lower sources fill in variables the higher ones leave unset, or whose cached server value Claude Code is withholding pending server confirmation. The telemetry unit and credential-paired routing variables follow their own rules; see Per-key exceptions across managed sources. Requires Claude Code v2.1.223 or later. Before v2.1.223, Claude Code applied the selected source's whole env block only

Parent settings from embedding hosts

An embedding host such as Claude Desktop can supply policy through the SDK managedSettings option. By default, Claude Code ignores those parent settings whenever an admin-deployed managed source is present: server-managed settings, an MDM or OS-level policy, or a managed settings file. The user-writable HKCU registry source doesn't count as admin-deployed.

To have Claude Code merge parent settings alongside an admin-deployed source, set parentSettingsBehavior to "merge" in the highest-priority managed source; Claude Code reads the key from that source only. It then passes the host's values through a restrictive-only filter, with one gap to know about: unless you also set the allowManaged*Only locks, allow-direction settings from the host, such as permission allow rules and sandbox allowlists, still apply. See Restrict parent settings for the locks. A policyHelper can turn parent merging off regardless of this key; that section says when.

Claude Code also applies these checks to specific parent-supplied values:

• When any admin-controlled managed source sets allowManagedPermissionRulesOnly, Claude Code drops parent-supplied permission allow rules and additionalDirectories as it reads them, even when a higher-priority source leaves the key unset. The key's effect on your own permission rules still comes from the highest-priority source only
• A forceLoginOrgUUID or allowedMcpServers value in the highest-priority admin source blocks a parent-supplied one, and Claude Code enforces the admin value. A value in a non-selected admin source neither applies nor blocks the parent's. Before v2.1.223, a value in any admin source blocked the parent's

Verify active settings

Run /status inside Claude Code to see which settings sources are active. Inside the menu, the Status tab includes a Setting sources line that lists each layer Claude Code loaded for the current session, such as User settings or Project local settings. When managed settings are in effect, the entry shows the delivery channel in parentheses, for example Enterprise managed settings (remote), (plist), (HKLM), (HKCU), or (file). The remote channel covers both claude.ai server-managed settings and Claude apps gateway-delivered policies. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.

The Setting sources line confirms which sources are being read. It does not show which layer supplied each individual key. The Config tab in the same dialog is an editor for a fixed set of toggles such as theme and verbose output, not a view of your settings.json contents.

If a user, project, or local settings file contains errors, such as invalid JSON or a value that fails validation, an interactive session shows a Settings Error dialog at startup. The dialog lets you fix the file with Claude's help, exit, or continue without the broken settings.

After you continue, /status lists the affected files. Run claude doctor to see the details for each error.

Managed settings entries that fail validation follow the more tolerant flow described in Invalid entries in managed settings: the file isn't rejected as a whole, and the remaining valid policies stay enforced.

Key points about the configuration system

• Memory files (CLAUDE.md): Contain instructions and context that Claude loads at startup
• Settings files (JSON): Configure permissions, environment variables, and tool behavior
• Skills: Custom prompts that can be invoked with /skill-name or loaded by Claude automatically
• MCP servers: Extend Claude Code with additional tools and integrations
• Precedence: Higher-level configurations (Managed) override lower-level ones (User/Project)
• Inheritance: Settings merge across scopes; scalar values from higher-priority scopes override and arrays concatenate, each with the exceptions described under Settings precedence

System prompt

Claude Code's internal system prompt is not published. To add custom instructions, use CLAUDE.md files or the --append-system-prompt flag.

Exclude sensitive files

To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the permissions.deny setting in your .claude/settings.json file:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

This replaces the deprecated ignorePatterns configuration. Claude Code excludes files matching these patterns from file discovery and search results, denies read operations on them, and blocks the Edit and Write tools on the matching paths.

Subagent configuration

Claude Code supports custom AI subagents that can be configured at both user and project levels. You define each subagent as a Markdown file with YAML frontmatter, saved in one of these locations:

• User subagents: ~/.claude/agents/, available across all your projects
• Project subagents: .claude/agents/, specific to your project and shareable with your team

Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the subagents documentation.

Plugin configuration

Claude Code supports a plugin system that lets you extend functionality with skills, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.

Plugin settings

Plugin-related settings in settings.json:

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

enabledPlugins

Controls which plugins are enabled. Format: "plugin-name@marketplace-name": true/false. A plugin with no entry at any scope falls back to its defaultEnabled value.

Scopes:

• User settings (~/.claude/settings.json): Personal plugin preferences
• Project settings (.claude/settings.json): Project-specific plugins shared with team
• Local settings (.claude/settings.local.json): Per-machine overrides, gitignored when Claude Code saves a setting to it
• Managed settings (managed-settings.json): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace

Example:

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

pluginConfigs

Stores the non-sensitive option values a plugin's userConfig prompt collects, keyed by plugin ID. Claude Code writes this key to user settings when you fill in the plugin's configuration dialog, so you don't need to edit it by hand. Sensitive options are stored in the macOS Keychain instead, or in ~/.claude/.credentials.json on platforms without a supported keychain.

This example stores one option for a plugin installed from the acme-tools marketplace:

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

pluginConfigs is read from user settings, the --settings flag, and managed settings only. Entries in a project's .claude/settings.json or .claude/settings.local.json are ignored, because these values are substituted 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.

extraKnownMarketplaces

Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.

When a repository's .claude/settings.json includes extraKnownMarketplaces, Claude Code adds those marketplaces for a team member after they accept the workspace trust dialog for that repository, with no separate prompt. In a folder they haven't trusted, including a -p run there, Claude Code ignores the entries without a message. What runs before you trust a folder compares this with the other content a repository can supply.

Example:

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

Marketplace source types:

• github: GitHub repository (uses repo)
• git: Any git URL (uses url)
• url: Direct URL to a marketplace.json file (uses url, plus optional headers for authenticated access)
• file: Local path to a marketplace.json file (uses path)
• directory: Local filesystem path (uses path, for development only)
• hostPattern: regex pattern to match marketplace hosts (uses hostPattern)
• settings: inline marketplace declared directly in settings.json without a separate hosted repository (uses 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.

Each marketplace entry also accepts an optional autoUpdate Boolean. Set "autoUpdate": true alongside source to make Claude Code refresh that marketplace and update its installed plugins in the background after startup. When omitted, official Anthropic marketplaces default to true and all other 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.

Use source: 'settings' to declare a small set of plugins inline without setting up a hosted marketplace repository. Plugins listed here must reference external sources such as GitHub or npm. You still need to enable each plugin separately in enabledPlugins.

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

Managed settings only: Controls which plugin marketplaces users are allowed to add and install plugins from. This setting can only be configured in managed settings and provides administrators with strict control over marketplace sources.

You can also write this key as allowedMarketplaces. Marketplace key aliases describes how Claude Code treats the alias and which version accepts it.

Managed settings file locations:

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

Key characteristics:

• Only available in managed settings (managed-settings.json)
• Cannot be overridden by user or project settings (highest precedence)
• Enforced before network and filesystem operations, so blocked sources never run
• Uses exact matching for most source specifications, including ref and path for git sources. hostPattern and pathPattern entries use regex matching. github entries with an owner-wildcard repo such as "acme-corp/*" follow their own matching rules. See Owner wildcards

Allowlist behavior:

• undefined (default): no restrictions, so users can add any marketplace
• Empty array []: complete lockdown that blocks every marketplace source, including the official Anthropic marketplace, so users can't add any new marketplaces
• List of sources: users can only add marketplaces that match an entry in the list

All supported source types:

The allowlist supports multiple marketplace source types. Most sources use exact matching. hostPattern and pathPattern use regex matching against the marketplace host and filesystem path respectively, and github entries can use an owner wildcard.

1. GitHub repositories:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/*" }

Fields: repo (required), ref (optional: branch or tag), path (optional: subdirectory)

The "acme-corp/*" form is an owner wildcard that matches every repository under that GitHub owner. Owner wildcards require Claude Code v2.1.223 or later. Claude Code accepts them 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. For the matching rules, see Owner wildcards.

2. Git repositories:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

Fields: url (required), ref (optional: branch or tag), path (optional: subdirectory)

3. URL-based marketplaces:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

Fields: url (required), headers (optional: HTTP headers for authenticated access)

4. NPM packages:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

Fields: package (required, supports scoped packages)

5. File paths:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

Fields: path (required: absolute path to marketplace.json file)

6. Directory paths:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

Fields: path (required: absolute path to directory containing .claude-plugin/marketplace.json)

7. Host pattern matching:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

Fields: hostPattern (required: regex pattern to match against the marketplace host)

Use host pattern matching when you want to allow all marketplaces from a specific host without enumerating each repository individually. This is useful for organizations with internal GitHub Enterprise or GitLab servers where developers create their own marketplaces.

Host extraction by source type:

• github: always matches against github.com
• git: extracts the hostname from the marketplace's git URL, depending on the 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.
• url: extracts hostname from the URL
• npm, file, directory: not supported for host pattern matching

8. Path pattern matching:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

Fields: pathPattern (required: regex pattern matched against the path field of file and directory sources)

Use path pattern matching to allow filesystem-based marketplaces alongside hostPattern restrictions for network sources. Set ".*" to allow all local paths, or a narrower pattern to restrict to specific directories.

Configuration examples:

Example: allow specific marketplaces only:

{
  "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"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

Example: disable all marketplace additions, including the official Anthropic marketplace:

{
  "strictKnownMarketplaces": []
}

Example: allow only the official Anthropic marketplace. Claude Code matches a single-repository entry exactly, so this entry doesn't cover ref or path variants of the same 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 doesn't cover every machine. It 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.

Example: allow all marketplaces from an internal git server:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Exact matching requirements:

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

• The repo or url must match exactly
• The ref field must match exactly (or both be undefined)
• The path field must match exactly (or both 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" }

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

Comparison with extraKnownMarketplaces:

Format difference:

strictKnownMarketplaces uses direct source objects:

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

extraKnownMarketplaces requires named marketplaces:

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

Using both together:

strictKnownMarketplaces is a policy gate: it controls what users may add but does not register any marketplaces. 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 manually via /plugin marketplace add. The official Anthropic marketplace is the only one Claude Code registers automatically, and only when the allowlist allows it. Automatic registration also misses some machines, most commonly non-interactive environments and machines where an earlier policy blocked the marketplace. To cover those machines, add the official marketplace to extraKnownMarketplaces too.

Important notes:

• Restrictions are checked before any network requests or filesystem operations
• When blocked, users see clear error messages indicating the source is blocked by managed policy
• The restriction is enforced on marketplace add and on plugin install, update, refresh, and auto-update. A marketplace added before the policy was set cannot be used to install or update plugins once its source no longer matches the allowlist
• Managed settings have the highest precedence and cannot be overridden

See Managed marketplace restrictions for user-facing documentation.

strictPluginOnlyCustomization

Managed settings only: blocks skills, agents, hooks, and MCP servers from user and project sources, so they can only come 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, and this setting blocks everything that doesn't come from a plugin or from managed settings.

The value is either true to lock all four surfaces, or an array naming the surfaces to lock:

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

For each locked surface, Claude Code skips user-level and project-level sources and loads only plugin-provided and managed sources:

Surface names that a Claude Code version doesn't recognize are ignored rather than failing the settings file, so you can add new surface names before all clients have updated.

Manage plugins

Use the /plugin command to manage plugins interactively:

• Browse available plugins from marketplaces
• Install/uninstall plugins
• Enable/disable plugins
• View plugin details (skills, agents, hooks provided)
• Add/remove marketplaces

Learn more about the plugin system in the plugins documentation.

Environment variables

Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in settings.json under the env key to apply it to every session or roll it out to your team.

See the environment variables reference for the full list.

Tools available to Claude

Claude Code has access to a set of tools for reading, editing, searching, running commands, and orchestrating subagents. Tool names are the exact strings you use in permission rules and hook matchers.

See the tools reference for the full list and Bash tool behavior details.

See also

• Permissions: permission system, rule syntax, tool-specific patterns, and managed policies
• Authentication: set up user access to Claude Code
• Debug your configuration: diagnose why a setting, hook, or MCP server isn't taking effect
• Troubleshoot installation and login: installation, authentication, and platform issues