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. Claude Code will configure git to ignore .claude/settings.local.json when it is created.
• 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 from Anthropic’s servers via the Claude.ai admin console. See server-managed settings.
  • MDM/OS-level policies: delivered through native device management on macOS and Windows:
    • macOS: com.anthropic.claudecode managed preferences domain (deployed via configuration profiles in Jamf, Kandji, or other 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; 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.
  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 preferences (theme, notification settings, editor mode), 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.

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

​

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

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

   Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

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

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "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')
your-repo-file-index --query "$query" | head -20

​

Hook configuration

• Managed hooks and SDK hooks are loaded
• User hooks, project hooks, and plugin hooks are blocked

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

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

​

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, precedence is: server-managed > MDM/OS-level policies > file-based (managed-settings.d/*.json + managed-settings.json) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.
2. Command line arguments
   • Temporary overrides for a specific session
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 are merged, with more specific settings adding to or overriding broader ones

​

System prompt

​

Excluding 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 can be shared with your team

​

Plugin configuration

​

Plugin settings

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "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 (not committed)

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

​

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/filesystem operations (blocked sources never execute)
• Uses exact matching for source specifications (including ref, path for git sources), except hostPattern, which uses regex matching

• undefined (default): No restrictions - users can add any marketplace
• Empty array []: Complete lockdown - users cannot 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://[email protected]/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

{
  "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 applies only to adding NEW marketplaces; previously installed marketplaces remain accessible
• Managed settings have the highest precedence and cannot be overridden

​

Managing plugins

• Browse available plugins from marketplaces
• Install/uninstall plugins
• Enable/disable plugins
• View plugin details (commands, 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
• Troubleshooting: solutions for common configuration issues