settings.json - Claude Code

The settings.json file controls Claude Code’s behavior, permissions, and features. Settings can be configured at multiple levels with a clear hierarchy.

Settings Hierarchy

Settings are loaded from multiple locations in priority order:

# 1. Managed settings (highest priority - enterprise)
managed-settings.json

# 2. User settings
~/.claude/settings.json

# 3. Project settings
project/.claude/settings.json

# 4. Local settings (lowest priority - not committed)
project/.claude/settings.local.json

Managed settings cannot be overridden by users when enterprise policies are enforced.

Permission Settings

Basic Permissions

Control which tools Claude can use:

{
  "permissions": {
    "allow": [
      "Read",
      "Write", 
      "Edit",
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "ask": [
      "Bash"
    ],
    "deny": [
      "WebSearch",
      "WebFetch"
    ]
  }
}

permissions.allow

string[]

Tools that are auto-approved without prompting.

permissions.ask

string[]

Tools that require user approval before execution.

permissions.deny

string[]

Tools that are completely blocked.

Permission Patterns

{
  "permissions": {
    "allow": [
      "Read",           // Allow all file reads
      "Bash(git:*)",    // Allow any git command
      "Bash(npm test:*)", // Allow npm test only
      "Bash(./scripts/deploy.sh:*)", // Allow specific script
      "MCPTool(github:*)" // Allow specific MCP tools
    ]
  }
}

Disable Bypass Mode

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

permissions.disableBypassPermissionsMode

'disable' | 'enable'

When set to "disable", prevents users from using --dangerously-skip-permissions flag.

Managed Permissions

{
  "allowManagedPermissionRulesOnly": true
}

allowManagedPermissionRulesOnly

boolean

default:false

When true, only managed settings can define permission rules. User and project-level allow/ask/deny are ignored.

Sandbox Settings

Configure bash command sandboxing for enhanced security.

Enable Sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true
  }
}

sandbox.enabled

boolean

default:false

Enable bash command sandboxing.

sandbox.autoAllowBashIfSandboxed

boolean

default:false

Auto-approve bash commands when running in sandbox mode.

Network Restrictions

{
  "sandbox": {
    "network": {
      "allowLocalBinding": false,
      "allowAllUnixSockets": false,
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowedDomains": ["api.github.com", "*.anthropic.com"],
      "httpProxyPort": 8080,
      "socksProxyPort": null
    }
  }
}

sandbox.network.allowLocalBinding

boolean

default:false

Allow binding to local network interfaces.

sandbox.network.allowAllUnixSockets

boolean

default:false

Allow access to all Unix sockets.

sandbox.network.allowUnixSockets

string[]

Specific Unix sockets that are allowed (e.g., Docker socket).

sandbox.network.allowedDomains

string[]

Domain whitelist. Supports wildcards (*.example.com).

sandbox.network.httpProxyPort

number | null

HTTP proxy port for sandbox network access.

sandbox.network.socksProxyPort

number | null

SOCKS proxy port for sandbox network access.

Excluded Commands

{
  "sandbox": {
    "excludedCommands": ["docker", "kubectl"],
    "allowUnsandboxedCommands": false
  }
}

sandbox.excludedCommands

string[]

Commands that bypass the sandbox (run normally).

sandbox.allowUnsandboxedCommands

boolean

default:true

When false, blocks commands in excludedCommands instead of running them unsandboxed.

Excluded commands run with full system access. Only exclude trusted commands.

Full Sandbox Example

settings-bash-sandbox.json

{
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

Plugin Settings

Plugin Marketplaces

{
  "strictKnownMarketplaces": [],
  "extraKnownMarketplaces": [
    {
      "name": "Company Internal",
      "url": "https://plugins.company.com/marketplace.json"
    }
  ]
}

strictKnownMarketplaces

array

When set to empty array [], blocks all public plugin marketplaces. Users can only install from extraKnownMarketplaces.

extraKnownMarketplaces

array

Additional plugin marketplaces to make available.Each entry has:

name - Display name
url - Marketplace JSON URL

Enabled Plugins

{
  "enabledPlugins": {
    "user": ["security-guidance", "code-review"],
    "project": ["project-specific-plugin"]
  }
}

Plugins can ship a settings.json file with default configuration that is automatically applied when the plugin is enabled.

Hook Settings

{
  "allowManagedHooksOnly": true,
  "disableAllHooks": false
}

allowManagedHooksOnly

boolean

default:false

When true, only managed hooks execute. User and project hooks are ignored.

disableAllHooks

boolean

default:false

When true, disables all hooks including managed hooks.Note: disableAllHooks in non-managed settings cannot disable managed hooks when allowManagedHooksOnly is set.

UI Settings

Theme

{
  "theme": "dark",
  "reducedMotion": false
}

theme

string

Color theme name (e.g., “dark”, “light”, “monokai”).

reducedMotion

boolean

default:false

Enable reduced motion mode for accessibility.

Spinner Customization

{
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": [
      "Custom tip 1",
      "Custom tip 2"
    ],
    "excludeDefault": true
  },
  "showTurnDuration": true
}

spinnerVerbs

string[]

Custom verbs for spinner display (e.g., “Thinking”, “Analyzing”).

spinnerTipsOverride

object

Customize spinner tips.

tips - Array of custom tip strings
excludeDefault - When true, only shows custom tips

showTurnDuration

boolean

default:true

Show duration messages like “Cooked for 1m 6s”.

Model Settings

Default Model

{
  "defaultModel": "claude-sonnet-4.6",
  "temperatureOverride": 1.0
}

defaultModel

string

Default model to use for new sessions.Available models:

claude-sonnet-4.6
claude-opus-4.6
claude-sonnet-4.5
claude-haiku-4

temperatureOverride

number

Override model temperature (0.0 - 1.0). Default is 1.0.

Thinking Mode

{
  "alwaysThinkingEnabled": true,
  "verboseMode": true
}

alwaysThinkingEnabled

boolean

default:false

Enable extended thinking mode for all requests.

verboseMode

boolean

default:false

Show thinking blocks and detailed processing information.

Context Settings

{
  "plansDirectory": "~/.claude/plans",
  "disableAllSkills": false
}

plansDirectory

string

Custom directory for storing plan files.

disableAllSkills

boolean

default:false

Disable all skills (built-in and custom).

Tool Settings

Disallowed Tools

{
  "disallowedTools": ["WebSearch", "WebFetch", "MCPSearch"]
}

disallowedTools

string[]

Tools that are completely unavailable (not shown to Claude).Common tools:

Bash, Read, Write, Edit, MultiEdit
Grep, Glob, FileSearch
WebSearch, WebFetch
MCPSearch, MCPTool
Task, TaskUpdate, TaskStop

MCP Tool Search

{
  "mcpToolSearch": "auto:10"
}

mcpToolSearch

'auto' | 'auto:N' | 'always' | 'never'

Configure MCP tool search behavior.

"auto" - Enable when tools exceed 10% of context
"auto:15" - Enable when tools exceed 15% of context
"always" - Always use tool search
"never" - Load all tools upfront

Environment Variables

Settings can reference environment variables:

{
  "sandbox": {
    "network": {
      "httpProxyPort": "${HTTP_PROXY_PORT}"
    }
  }
}

Example Configurations

Strict Security

Maximum security for enterprise environments:

settings-strict.json

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "ask": ["Bash"],
    "deny": ["WebSearch", "WebFetch"]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "strictKnownMarketplaces": [],
  "sandbox": {
    "autoAllowBashIfSandboxed": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

Permissive Development

Relaxed settings for local development:

settings-lax.json

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  },
  "strictKnownMarketplaces": []
}

Sandbox Only

Enforce sandboxing for all bash commands:

settings-bash-sandbox.json

{
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "excludedCommands": [],
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

Managed Settings Deployment

Enterprise organizations can deploy managed settings via:

macOS (plist)

# Set managed settings location
defaults write com.anthropic.claude-code managedSettingsPath \
  "/etc/claude/managed-settings.json"

Windows (Registry)

HKEY_LOCAL_MACHINE\SOFTWARE\Anthropic\ClaudeCode
  managedSettingsPath = "C:\ProgramData\Claude\managed-settings.json"

Environment Variable

export CLAUDE_MANAGED_SETTINGS_PATH="/etc/claude/managed-settings.json"

Learn more at Settings Documentation.

Validation

Before deploying settings:

Validate JSON syntax
```
jq . settings.json
```

Test locally

# Copy to local settings
cp settings.json ~/.claude/settings.local.json
claude

Check for conflicts
- Ensure managed settings take precedence
- Verify permission rules are correct
- Test with actual workflows

Troubleshooting

Settings not taking effect

Check:

JSON is valid (use jq to validate)
File is in correct location
Restart Claude Code after changes
Check for higher-priority settings overriding

Permission rules not working

Verify:

Pattern syntax is correct (Bash(git:*))
No typos in tool names
allowManagedPermissionRulesOnly isn’t blocking user rules
Check /config to see active permissions

Sandbox not working

Check:

sandbox.enabled is true
Required dependencies installed
Platform support (Linux, macOS)
Run /sandbox to see status

Managed settings being overridden

Ensure:

Using correct managed settings path
File permissions are correct
allowManagedPermissionRulesOnly is set in managed file
No disableAllHooks in user settings

Next Steps

CLAUDE.md

Configure project context with CLAUDE.md files

plugin.json

Learn about plugin configuration

Commands

Hooks

Configuration Files

​Settings Hierarchy

​Permission Settings

​Basic Permissions

​Permission Patterns

​Disable Bypass Mode

​Managed Permissions

​Sandbox Settings

​Enable Sandbox

​Network Restrictions

​Excluded Commands

​Full Sandbox Example

​Plugin Settings

​Plugin Marketplaces

​Enabled Plugins

​Hook Settings

​UI Settings

​Theme

​Spinner Customization

​Model Settings

​Default Model

​Thinking Mode

​Context Settings

​Tool Settings

​Disallowed Tools

​MCP Tool Search

​Environment Variables

​Example Configurations

​Strict Security

​Permissive Development

​Sandbox Only

​Managed Settings Deployment

​macOS (plist)

​Windows (Registry)

​Environment Variable

​Validation

​Troubleshooting

​Next Steps

CLAUDE.md

plugin.json

Build docs developers (and LLMs) love

Settings Hierarchy

Permission Settings

Basic Permissions

Permission Patterns

Disable Bypass Mode

Managed Permissions

Sandbox Settings

Enable Sandbox

Network Restrictions

Excluded Commands

Full Sandbox Example

Plugin Settings

Plugin Marketplaces

Enabled Plugins

Hook Settings

UI Settings

Theme

Spinner Customization

Model Settings

Default Model

Thinking Mode

Context Settings

Tool Settings

Disallowed Tools

MCP Tool Search

Environment Variables

Example Configurations

Strict Security

Permissive Development

Sandbox Only

Managed Settings Deployment

macOS (plist)

Windows (Registry)

Environment Variable

Validation

Troubleshooting

Next Steps