Claude Code settings

​

Configuration scopes

​

Available scopes

​

When to use each scope

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

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

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

• 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

1. Managed (highest): can’t be overridden by anything
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

​

What uses scopes

​

Settings files

• 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 creates .claude/settings.local.json, it configures git to ignore the file. If you create the file yourself, add it to your gitignore manually. 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.
    Before v2.1.211, the file always lived in the starting directory. Claude Code still reads a .claude/settings.local.json that an earlier version left there. When both files set the same key, the repository root’s value wins, except that permission rules from both files stay in effect.
    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\
    The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to C:\Program Files\ClaudeCode\managed-settings.json.
    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, managed-settings.json is merged first as the base, then all *.json files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values, arrays are concatenated and de-duplicated, and objects are deep-merged. Hidden files starting with . are ignored. 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.
  Managed deployments can also restrict plugin marketplace additions using strictKnownMarketplaces. For more information, see Managed marketplace restrictions.
• 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.

• 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"
  },
  "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"
  ]
}

​

When edits take effect

• 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

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

​

Available settings

​

Global config settings

​

Worktree settings

​

Permission settings

​

Permission rule syntax

​

Sandbox settings

​

Sandbox path prefixes

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

• sandbox.filesystem settings (shown above): Control paths at the OS-level sandbox boundary. 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 tool 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

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

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

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

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

​

File suggestion settings

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

{"query": "src/comp"}

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

#!/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

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

​

Hook configuration

• 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, and all other plugin hooks are blocked

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

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

​

Compute managed settings with a policy helper

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

​

Settings precedence

1. Managed settings (server-managed, MDM/OS-level policies, or managed settings)
   • Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files
   • Cannot be overridden by any other level, including command line arguments
   • Within the managed tier, only one source is used and the others are ignored rather than merged. Precedence, highest first:
     • policyHelper output: when configured, this is the only managed source used
     • Remote (claude.ai server-managed or Claude apps gateway-delivered)
     • MDM/OS-level policies
     • File-based (managed-settings.d/*.json and managed-settings.json, merged together)
     • HKCU registry (Windows only)
   • A few keys are exceptions, honored when any admin-controlled managed source sets them rather than only the winning source. The user-writable HKCU registry source is excluded. The exception 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
     • forceRemoteSettingsRefresh
   • Embedding hosts such as Claude Desktop can supply policy via the SDK managedSettings option. By default this is ignored when 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 fallback does not count as an admin-deployed source. Administrators can opt in by setting parentSettingsBehavior to "merge". The embedder’s values are filtered so they can tighten managed policy but not loosen it.
2. Command line arguments
   • Temporary overrides for a specific session. JSON passed via --settings <file-or-json> merges with file-based settings using the same rules as the other layers: a key set here overrides the same key in local, project, or user settings, and omitting a key leaves the lower-layer value in place
3. Local project settings (.claude/settings.local.json)
   • Personal project-specific settings
4. Shared project settings (.claude/settings.json)
   • Team-shared project settings in source control
5. User settings (~/.claude/settings.json)
   • Personal global settings

​

Verify active settings

​

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, with two exceptions described in the array-merge Note

​

System prompt

​

Exclude sensitive files

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

​

Subagent configuration

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

​

Plugin configuration

​

Plugin settings

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

• 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 creates it
• Managed settings (managed-settings.json): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace

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

​

pluginConfigs

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

​

extraKnownMarketplaces

1. Team members are prompted to install the marketplace when they trust the folder
2. Team members are then prompted to install plugins from that marketplace
3. Users can skip unwanted marketplaces or plugins (stored in user settings)
4. Installation respects trust boundaries and requires explicit consent

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

• github: GitHub repository (uses repo)
• git: Any git URL (uses url)
• 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)

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

​

strictKnownMarketplaces

• 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

• 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 source specifications (including ref, path for git sources), except hostPattern and pathPattern, which use regex matching

• undefined (default): no restrictions, so users can add any marketplace
• Empty array []: complete lockdown, so users can’t add any new marketplaces
• List of sources: users can only add marketplaces that match exactly

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

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

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

4. NPM packages:

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

5. File paths:

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

6. Directory paths:

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

7. Host pattern matching:

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

• github: always matches against github.com
• git: extracts hostname from the URL (supports both HTTPS and SSH formats)
• 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": ".*" }

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

{
  "strictKnownMarketplaces": []
}

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

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

// These are DIFFERENT sources:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// These are also DIFFERENT:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

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

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

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

• 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

​

strictPluginOnlyCustomization

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

​

Manage plugins

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

​

Environment variables

​

Tools available to Claude

​

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