Settings Builder
🔐 Authentication & Login Managed Only
Force authentication method and organization for all users
Force Login Method
forceLoginMethod
Restrict which login flow users can use. "claudeai" = Claude Pro/Max subscription, "console" = Anthropic Console API billing.
Force Organization UUID
forceLoginOrgUUID
Pre-select the organization for OAuth login. Users will be locked to this org.
API Key Helper Script
apiKeyHelper
Path to a script that outputs auth values. Used as X-Api-Key and Authorization: Bearer headers.
AWS Auth Refresh
awsAuthRefresh
Command to refresh AWS credentials (for Bedrock users).
AWS Credential Export
awsCredentialExport
Script for advanced AWS credential configuration.
🛡 Permissions
Control which tools Claude can use. Rules: deny → ask → allow (first match wins)
Rule syntax:
Tools:
Patterns:
ToolName or ToolName(pattern)Tools:
Bash Read Edit Write MultiEdit WebFetch WebSearch Glob Grep LS Task TodoWrite NotebookEdit NotebookRead mcp__servernamePatterns:
Bash(curl:*) Read(**/.env) WebFetch(domain:example.com) Edit(**/*.prod.*)
Disable bypassPermissions Mode
disableBypassPermissionsMode
Prevent users from using the dangerous --dangerously-skip-permissions flag.
Managed Permission Rules Only
allowManagedPermissionRulesOnly
Managed Only
Prevent user/project settings from defining their own allow, ask, or deny rules. Only managed-level rules apply.
Default Permission Mode
defaultMode
Default mode when starting a session.
✕ Deny Rules
Blocked unconditionally. Evaluated first.
Read(**/.env)
Read(**/.env.*)
Read(**/secrets/**)
Read(**/*.key)
Read(**/*.pem)
Bash(sudo:*)
Bash(su:*)
Bash(curl:*)
Bash(wget:*)
Bash(ssh:*)
Bash(rm -rf:*)
Bash(git push --force:*)
Bash(npm publish:*)
WebFetch
WebSearch
Bash (all)
Edit (all)
Write (all)
MultiEdit
NotebookEdit
✓ Allow Rules
Auto-approved without prompting.
Read
Bash(npm run lint)
Bash(npm run test *)
Bash(git diff:*)
Bash(git log:*)
Bash(git status)
Bash(find:*)
Glob
Grep
LS
? Ask Rules
Always prompt the user for confirmation.
Bash (all)
Bash(rm:*)
Bash(docker run:*)
Bash(git push:*)
WebFetch
WebSearch
Edit
Write
Additional Directories
additionalDirectories
Extra directories Claude can access as context.
📦 Sandbox (Bash Isolation)
Sandbox only applies to the Bash tool — not Read, Write, WebFetch, MCPs, hooks, or internal commands.
Sandbox Enabled
sandbox.enabled
Explicitly enable or disable the sandbox. When enabled, Bash commands run in an isolated environment.
Auto-Allow Bash if Sandboxed
autoAllowBashIfSandboxed
When sandbox is active, skip Bash permission prompts.
Allow Unsandboxed Commands
allowUnsandboxedCommands
When a command fails in sandbox, allow Claude to retry outside the sandbox (with permission). Set false to disable this escape hatch entirely. Default: true.
Enable Weaker Nested Sandbox
enableWeakerNestedSandbox
For unprivileged Docker environments where --proc mounting fails. Significantly reduces sandbox strength.
Excluded Commands
excludedCommands
Commands that should always run outside the sandbox (e.g. docker, git, uv). Different from unsandboxedCommands.
docker
docker-compose
git
uv
watchman
Network — Allowed Domains
Whitelist of domains for outbound connections. Supports wildcards like
*.npmjs.org
github.com
*.npmjs.org
registry.yarnpkg.com
pypi.org
files.pythonhosted.org
crates.io
Allow Local Binding
allowLocalBinding
Allow binding to 127.0.0.1 and ::1 (localhost ports).
Allow All Unix Sockets
allowAllUnixSockets
Permit all Unix socket connections. Insecure — prefer specific paths.
Allowed Unix Sockets
Specific Unix socket paths (SSH agent, Docker daemon, etc.)
HTTP Proxy Port
httpProxyPort
Port for HTTP proxy routing inside the sandbox.
SOCKS Proxy Port
socksProxyPort
Port for SOCKS proxy routing inside the sandbox.
Unsandboxed Commands
unsandboxedCommands
Commands that should never run inside the sandbox.
Filesystem — Allow Write
allowWrite
Paths where sandbox allows write access. Prefix: /tmp/build = absolute, ./src = project-relative, ~/.kube = home-relative.
Filesystem — Deny Write
denyWrite
Paths to deny write access to inside the sandbox.
Filesystem — Deny Read
denyRead
Paths to deny read access to inside the sandbox.
Filesystem — Allow Read
allowRead
Re-allow read access within denyRead regions (added v2.1.77). Whitelist specific subdirectories.
🪝 Hook Controls
Lifecycle hooks run shell commands before/after tool executions
Disable All Hooks
disableAllHooks
Disable all hooks and custom status line execution.
Allow Managed Hooks Only
allowManagedHooksOnly
Managed Only
Block all user, project, and plugin hooks. Only managed + SDK hooks run.
Allowed HTTP Hook URLs
allowedHttpHookUrls
Restrict which URLs HTTP hooks can target. Supports * wildcards. Empty array = block all HTTP hooks.
Allowed HTTP Hook Env Vars
httpHookAllowedEnvVars
Restrict which env var names HTTP hooks can interpolate into headers.
🔌 MCP Server Controls
Control which Model Context Protocol servers are enabled or blocked
🚫 Block All .mcp.json Servers
Sets
enabledMcpjsonServers to an empty array []. No servers from .mcp.json will load — regardless of what developers define.
Enable All Project MCP Servers
enableAllProjectMcpServers
Auto-approve all MCP servers defined in project .mcp.json files.
✓ Enabled MCP Servers
enabledMcpjsonServers
Specific MCP servers from .mcp.json to approve.
✕ Disabled MCP Servers
disabledMcpjsonServers
Specific MCP servers from .mcp.json to reject.
Policy-Based MCP Control Managed Only
These are a separate system from enabledMcpjsonServers above. They go in
Each entry uses
These are a separate system from enabledMcpjsonServers above. They go in
managed-settings.json and control which MCP servers are permitted org-wide — regardless of what developers put in their .mcp.json.Each entry uses
{"serverName": "..."} format. The denylist takes absolute precedence over the allowlist.
✓ Allowed MCP Servers
allowedMcpServers
Managed Only
Policy allowlist — only these MCP servers are permitted across the org. Uses {"serverName": "..."} object format.
github
sentry
playwright
memory
postgres
supabase
figma
linear
azure-devops
aws-knowledge-base
✕ Denied MCP Servers
deniedMcpServers
Managed Only
Policy denylist — these MCP servers are blocked org-wide. Takes absolute precedence over the allowlist. Uses {"serverName": "..."} object format.
filesystem
🧩 Plugins & Marketplaces
Control plugin sources and marketplace restrictions
Strict Known Marketplaces
strictKnownMarketplaces
Managed Only
Restrict plugin installation to approved marketplace sources only. Empty array = block ALL marketplaces (including official). Add GitHub repos in owner/repo format.
Leave empty & enable toggle below to block all marketplaces.
Enable strict mode (empty = block all)
🌐 Environment Variables
Set environment variables applied to every Claude Code session
| Variable | Value |
|---|
Disable nonessential traffic
Disable telemetry
Disable auto-updater
Disable error reporting
Disable /bug command
Disable cost warnings
Disable flavor text
Disable terminal title
Skip IDE auto-install
Enable OTEL telemetry
OTEL metrics: otlp
OTEL logs: otlp
Use AWS Bedrock
Use Google Vertex
Maintain project CWD
Use system ripgrep
🤖 Model & Output
Override default model and output behavior
Model
model
Override the default model. Examples: claude-sonnet-4-6, claude-opus-4-6
Small/Fast Model (env)
ANTHROPIC_SMALL_FAST_MODEL
Haiku-class model for background tasks. Set via env vars section, shown here for reference.
Output Style
outputStyle
Controls the output style for assistant responses.
Always Enable Thinking
alwaysThinkingEnabled
Force extended thinking to be always enabled.
Skip WebFetch Preflight
skipWebFetchPreflight
Skip the WebFetch blocklist check for enterprise environments with restrictive security policies.
OTEL Headers Helper
otelHeadersHelper
Path to a script that outputs OpenTelemetry headers for auth.
⚡ General Settings
Retention, updates, attribution, and misc preferences
Transcript Retention
cleanupPeriodDays
Days to retain local session transcripts. Default: 30.
Disable Auto Updates
autoUpdates
Disable automatic Claude Code updates.
Exclude Co-Authored-By
includeCoAuthoredBy
Remove the "co-authored-by Claude" byline from git commits and PRs.
Disable Git Instructions
includeGitInstructions
Remove built-in commit and PR workflow instructions from Claude's system prompt.
Spinner Tips
spinnerTipsEnabled
Show tips in the loading spinner. Set false to disable.
Verbose Output
verbose
Show full bash and command outputs in the terminal.
Theme
theme
Color theme for Claude Code terminal UI.
Notification Channel
preferredNotifChannel
Where to receive notifications when Claude finishes a task.
Git Attribution — Commit Message
attribution.commitMessage
Custom commit attribution text. Set to empty string "" to hide. Replaces deprecated includeCoAuthoredBy.
Git Attribution — Pull Request
attribution.pullRequest
Custom PR attribution text. Set to empty string "" to hide.
Status Line Command
statusLine
Custom status line display. A shell command whose output is shown in the status bar. Requires workspace trust.
📢 Company Announcements
Messages shown to all developers at Claude Code startup
📖 Reference: File Locations & Precedence
managed-settings.json paths:
macOS:
Linux/WSL:
Windows:
MDM / OS-level policies:
macOS:
Windows:
Windows (user):
Precedence (highest → lowest):
1. Server-managed (Anthropic admin console)
2. MDM / OS-level policies
3. managed-settings.json file
4. HKCU registry (Windows only)
5. CLI arguments (--settings)
6. .claude/settings.local.json
7. .claude/settings.json
8. ~/.claude/settings.json
Managed-only keys (only effective in managed settings):
macOS:
/Library/Application Support/ClaudeCode/managed-settings.jsonLinux/WSL:
/etc/claude-code/managed-settings.jsonWindows:
C:\Program Files\ClaudeCode\managed-settings.jsonMDM / OS-level policies:
macOS:
com.anthropic.claudecode managed preferences domainWindows:
HKLM\SOFTWARE\Policies\ClaudeCode registry (REG_SZ "Settings" value)Windows (user):
HKCU\SOFTWARE\Policies\ClaudeCode (lowest policy priority)Precedence (highest → lowest):
1. Server-managed (Anthropic admin console)
2. MDM / OS-level policies
3. managed-settings.json file
4. HKCU registry (Windows only)
5. CLI arguments (--settings)
6. .claude/settings.local.json
7. .claude/settings.json
8. ~/.claude/settings.json
Managed-only keys (only effective in managed settings):
allowManagedHooksOnly, allowManagedPermissionRulesOnly, strictKnownMarketplaces, forceLoginMethod, forceLoginOrgUUID
📚 Complete Settings Reference
Every key explained — what it does, accepted values, where it works, and when to use it.
Table of Contents
1. Overview: managed-settings.json vs settings.json
2. Authentication & Login
3. Permissions
4. Sandbox (Bash Isolation)
5. Hook Controls
6. MCP Server Controls
7. Plugins & Marketplaces
8. Environment Variables
9. Model & Output
10. General Settings
11. Company Announcements
12. Tool Names & Pattern Syntax
13. Settings Precedence & Merge Behavior
14. File Paths by OS
15. Common Policy Presets
1. Overview: managed-settings.json vs settings.json
2. Authentication & Login
3. Permissions
4. Sandbox (Bash Isolation)
5. Hook Controls
6. MCP Server Controls
7. Plugins & Marketplaces
8. Environment Variables
9. Model & Output
10. General Settings
11. Company Announcements
12. Tool Names & Pattern Syntax
13. Settings Precedence & Merge Behavior
14. File Paths by OS
15. Common Policy Presets
1. Overview: managed-settings.json vs settings.json
Both files use the exact same JSON format and accept the same keys. The difference is where they live and who can override them.
| Aspect | managed-settings.json | settings.json |
|---|---|---|
| Purpose | Enterprise-wide security enforcement | User preferences & project conventions |
| Who deploys it | IT / DevOps via MDM, Group Policy, or manual placement | Individual developers or team leads (committed to git) |
| Can be overridden? | No — highest priority after server-managed and MDM policies | Yes — overridden by managed settings, CLI args, and local settings |
| Requires admin privileges? | Yes — lives in system directories | No — lives in user home or project directory |
| Managed-only keys work? | Yes — allowManagedHooksOnly, allowManagedPermissionRulesOnly, strictKnownMarketplaces, forceLoginMethod, forceLoginOrgUUID | No — these keys are silently ignored |
Tip: Even if you're not part of an enterprise, you can use managed-settings.json as your own master policy. It cannot be overridden by project or user settings, making it a reliable safety net.
Server-managed settings (delivered via the Claude.ai admin console) sit above managed-settings.json in precedence. Within the managed tier: server-managed > MDM/OS policies > managed-settings.json > HKCU registry. Only one managed source is used — they do not merge.
2. Authentication & Login
Control how developers authenticate with Claude Code. These are typically deployed via managed settings to ensure all users connect through the correct billing account and organization.
| Key | Type | Scope | Description |
|---|---|---|---|
forceLoginMethod |
"claudeai" | "console" | Managed | Forces a specific login flow. "claudeai" = Claude Pro/Max subscription billing. "console" = Anthropic Console API billing. When set, the user is not shown a choice — they go directly to the specified login method. |
forceLoginOrgUUID |
string | Managed | Organization UUID to pre-select during OAuth login. Locks all users to a specific organization so they can't switch to personal accounts. Find your org UUID in the Claude.ai admin console. |
apiKeyHelper |
string (path) | Any | Path to a shell script (/bin/sh) that outputs an authentication value. This value is sent as both X-Api-Key and Authorization: Bearer headers for model requests. Useful for rotating credentials or using secret managers. |
awsAuthRefresh |
string (command) | Any | Command to refresh AWS credentials from the .aws directory. For Bedrock users who need SSO-based credential rotation. Example: aws sso login --profile myprofile |
awsCredentialExport |
string (path) | Any | Path to a script for advanced AWS credential configuration. Used when the standard AWS credential chain isn't sufficient (e.g., assume-role workflows or custom credential providers). |
⚠ Note:
forceLoginMethod and forceLoginOrgUUID only take effect in managed settings. If placed in a regular settings.json, they are ignored. There's a known issue where the VSCode extension may not respect these settings — the CLI does.
3. Permissions
The permission system controls which tools Claude Code can invoke and under what conditions. Rules are evaluated in strict order: deny → ask → allow. The first matching rule wins. If no rule matches, Claude prompts the user.
| Key | Type | Scope | Description |
|---|---|---|---|
permissions.deny |
string[] | Any | Array of tool rules that are blocked unconditionally. Deny rules are checked first and cannot be overridden — even in bypassPermissions mode, deny rules still block. Uses the pattern syntax described in the Tool Names section below. |
permissions.allow |
string[] | Any | Array of tool rules that are auto-approved without prompting. Checked after deny and ask rules. If a tool matches an allow rule and no deny/ask rule, it runs silently. |
permissions.ask |
string[] | Any | Array of tool rules that always prompt the user for confirmation, even if the same tool appears in an allow rule at a lower scope. Checked after deny but before allow. |
permissions.defaultMode |
"default" | "acceptEdits" | "plan" | "bypassPermissions" | Any | default — prompts for permission on first use of each tool. acceptEdits — auto-accepts file edits, still asks for other tools. plan — read-only mode, Claude can analyze but not modify files or run commands. bypassPermissions — auto-accepts everything (except deny rules). Extremely dangerous. |
permissions.disableBypassPermissionsMode |
"disable" | Any | When set to "disable", prevents the bypassPermissions mode and the --dangerously-skip-permissions CLI flag from being used. Strongly recommended for any managed deployment. |
permissions.additionalDirectories |
string[] | Any | Allow-list of additional directories Claude can access as context beyond the current working directory. Be cautious — any content in these directories may be sent to the model. |
allowManagedPermissionRulesOnly |
boolean | Managed | When true, completely ignores all allow, deny, and ask rules defined in user or project settings. Only managed-level permission rules apply. This prevents developers from escalating their own permissions. |
Merge behavior: Array settings like
permissions.allow merge (concatenate + deduplicate) across scopes. A project's deny rules add to, rather than replace, user-level deny rules. However, when allowManagedPermissionRulesOnly is true, lower-scope arrays are entirely ignored.
4. Sandbox (Bash Isolation)
The sandbox isolates Bash command execution with controlled filesystem and network access. Important: the sandbox only applies to the Bash tool. It does not apply to Read, Write, WebSearch, WebFetch, MCPs, hooks, or internal commands.
| Key | Type | Description |
|---|---|---|
sandbox.autoAllowBashIfSandboxed |
boolean | When the sandbox is active, skip Bash permission prompts entirely. The logic: if Bash is sandboxed, it's safe enough to auto-approve. Set to false if you still want prompts even within the sandbox. |
sandbox.enableWeakerNestedSandbox |
boolean | Enable a weaker sandbox mode for unprivileged Docker environments where --proc mounting fails. Significantly reduces sandbox strength — only use when the full sandbox can't be initialized. |
sandbox.unsandboxedCommands |
string[] | Commands that should never run inside the sandbox. Example: ["git", "docker"]. These commands bypass sandbox restrictions. Use sparingly. |
sandbox.network.allowedDomains |
string[] | Whitelist of domains for outbound HTTPS/HTTP connections from sandboxed Bash commands. Supports wildcards: *.npmjs.org. If empty or unset, network access may be fully blocked depending on sandbox mode. |
sandbox.network.allowLocalBinding |
boolean | Allow binding to local network addresses (127.0.0.1 and ::1). Needed for local dev servers. Default: false. |
sandbox.network.allowAllUnixSockets |
boolean | Permit all Unix domain socket connections. Insecure — prefer listing specific paths in allowUnixSockets instead. |
sandbox.network.allowUnixSockets |
string[] | Specific Unix socket paths to allow. Example: ["/var/run/docker.sock"] for Docker daemon access, or SSH agent sockets. Default: blocked if not specified. |
sandbox.filesystem.read.denyOnly |
string[] | Paths to deny read access to inside the sandbox. Example: ["~/.ssh/", "/etc/shadow"] |
sandbox.filesystem.write.allowOnly |
string[] | Restrict write access to only these paths. Everything else is read-only. Example: ["./src/", "./dist/"] |
sandbox.filesystem.write.includeDefaults |
boolean | When using allowOnly, whether to also include the default write paths. Default: true. |
sandbox.filesystem.write.denyWithinAllow |
string[] | Paths to deny write access to even within allowed paths. Example: ["./.claude"] prevents Claude from modifying its own config even if the parent directory is writable. |
sandbox.ignoreViolations |
object | Map of command patterns to filesystem paths where sandbox violations should be ignored. Key is a command pattern (or "*" for all), value is an array of paths. Use for known false positives. |
5. Hook Controls
Hooks execute shell commands or LLM prompts at lifecycle events (PreToolUse, PostToolUse, Setup, Stop, etc.). These settings control whether hooks can run and which HTTP endpoints they can reach.
| Key | Type | Scope | Description |
|---|---|---|---|
disableAllHooks |
boolean | Any | Disable all hooks and any custom status line execution. Nuclear option — nothing runs. |
allowManagedHooksOnly |
boolean | Managed | When true: managed hooks and SDK hooks are loaded; user hooks, project hooks, and plugin hooks are blocked. This prevents developers from injecting custom scripts via lifecycle hooks. |
allowedHttpHookUrls |
string[] | Any | Allowlist of URL patterns that HTTP hooks may target. Supports * as wildcard. When this array is defined, hooks targeting non-matching URLs are silently blocked. Undefined = no restriction. Empty array = block ALL HTTP hooks. Arrays merge across settings sources. |
httpHookAllowedEnvVars |
string[] | Any | Allowlist of environment variable names HTTP hooks can interpolate into header values. Each hook's effective allowed env vars is the intersection of its own list and this setting. Undefined = no restriction. Arrays merge across sources. |
hooks |
object | Any | Define actual hook commands. Keys are lifecycle events (PreToolUse, PostToolUse, etc.), values are arrays of matcher + hook definitions. Each hook has a type ("command"), command (shell command), and optional timeout (seconds). |
Common pattern: Set
allowManagedHooksOnly: true in managed settings, then define your approved hooks in the same managed-settings.json under the hooks key. This ensures only IT-approved scripts run.
6. MCP Server Controls
MCP (Model Context Protocol) servers extend Claude Code with additional tools like database access, GitHub integration, browser automation, etc. MCP server definitions live in
.mcp.json (project) or ~/.claude.json (user), but these settings control which servers are approved. For enterprise managed MCP configs, use managed-mcp.json alongside managed-settings.json.
| Key | Type | Description |
|---|---|---|
enableAllProjectMcpServers |
boolean | Auto-approve all MCP servers defined in project .mcp.json files. Convenient but risky — means any server a developer adds to the project config is automatically trusted. |
enabledMcpjsonServers |
string[] | Specific MCP server names from .mcp.json to approve. More granular than enableAllProjectMcpServers. Example: ["github", "memory", "sentry"] |
disabledMcpjsonServers |
string[] | Specific MCP server names from .mcp.json to reject. Overrides enableAllProjectMcpServers for these specific servers. Example: ["filesystem"] |
Permission rules for MCP tools: You can also control MCP tools via the permission system using the pattern
mcp__servername in deny/allow/ask arrays. This does NOT support wildcards — you must list each MCP tool individually.
7. Plugins & Marketplaces
Plugins are packaged bundles of skills, subagents, hooks, and MCP servers distributed through marketplaces. These settings control which plugin sources are trusted.
| Key | Type | Scope | Description |
|---|---|---|---|
strictKnownMarketplaces |
array of objects | Managed | Restrict plugin installation to these approved marketplace sources only. Each entry is an object with source and repo (for GitHub). Empty array [] = block ALL marketplaces, including the official Anthropic one. Restrictions are checked before any network requests. |
extraKnownMarketplaces |
object | Any | Register additional marketplace sources. Keys are marketplace names, values are objects specifying the source (github, url, npm, git, file, directory). Use alongside strictKnownMarketplaces to both restrict AND pre-register approved sources. |
enabledPlugins |
object | Any | Explicitly enable specific plugins using plugin-id@marketplace-id format. Values can be true (boolean) or an array of version constraints. |
skippedMarketplaces |
string[] | Any | Marketplace names the user has chosen not to install when prompted. Prevents repeated prompting. |
skippedPlugins |
string[] | Any | Plugin IDs (in plugin@marketplace format) the user has declined to install. |
Using both together:
strictKnownMarketplaces is a policy gate (controls what users MAY add). extraKnownMarketplaces registers sources (makes them available). To both restrict AND auto-register, set both in your managed-settings.json.
8. Environment Variables
The
env object sets environment variables applied to every Claude Code session. These override same-named system environment variables. You can also set them in your shell profile, but placing them in settings.json ensures they persist across sessions and can be deployed via managed settings.
| Variable | Description |
|---|---|
ANTHROPIC_MODEL | Name of custom model to use (alternative to the model key) |
ANTHROPIC_SMALL_FAST_MODEL | Haiku-class model for background tasks (tab completion, status summaries) |
BASH_DEFAULT_TIMEOUT_MS | Default timeout in milliseconds for long-running bash commands |
BASH_MAX_TIMEOUT_MS | Maximum timeout the model can set for long-running bash commands |
BASH_MAX_OUTPUT_LENGTH | Maximum characters in bash output before middle-truncation kicks in |
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR | Return to the original working directory after each Bash command. Set to 1 |
CLAUDE_CODE_API_KEY_HELPER_TTL_MS | Interval in milliseconds at which credentials from apiKeyHelper should be refreshed |
CLAUDE_CODE_MAX_OUTPUT_TOKENS | Set the maximum number of output tokens for most requests |
MAX_THINKING_TOKENS | Force a thinking budget for the model |
MAX_MCP_OUTPUT_TOKENS | Maximum tokens allowed in MCP tool responses (default: 25000) |
MCP_TIMEOUT | Timeout in milliseconds for MCP server startup |
MCP_TOOL_TIMEOUT | Timeout in milliseconds for MCP tool execution |
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC | All-in-one toggle: disables auto-updater, /bug command, error reporting, and telemetry |
DISABLE_TELEMETRY | Opt out of Statsig telemetry (does not include user data like code or file paths) |
DISABLE_ERROR_REPORTING | Opt out of Sentry error reporting |
DISABLE_AUTOUPDATER | Disable automatic updates. Takes precedence over the autoUpdates setting key |
DISABLE_BUG_COMMAND | Disable the /bug command |
DISABLE_COST_WARNINGS | Disable cost warning messages |
DISABLE_NON_ESSENTIAL_MODEL_CALLS | Disable model calls for non-critical paths like flavor text ("Great, now let's...") |
CLAUDE_CODE_DISABLE_TERMINAL_TITLE | Disable automatic terminal title updates based on conversation context |
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL | Skip auto-installation of IDE extensions (VS Code) |
CLAUDE_CODE_ENABLE_TELEMETRY | Enable OpenTelemetry telemetry export (for enterprise monitoring) |
OTEL_METRICS_EXPORTER | OpenTelemetry metrics exporter format (e.g., otlp) |
OTEL_LOGS_EXPORTER | OpenTelemetry logs exporter format (e.g., otlp) |
OTEL_EXPORTER_OTLP_ENDPOINT | OTLP collector endpoint URL |
OTEL_RESOURCE_ATTRIBUTES | Resource attributes for filtering metrics by team/department. Example: team.name=platform,department=engineering |
CLAUDE_CODE_USE_BEDROCK | Set to 1 to use Amazon Bedrock as the model provider |
CLAUDE_CODE_USE_VERTEX | Set to 1 to use Google Vertex AI as the model provider |
HTTP_PROXY / HTTPS_PROXY | Specify proxy servers for network connections |
USE_BUILTIN_RIPGREP | Set to 0 to use system-installed rg instead of the bundled version |
CLAUDE_CODE_TMPDIR | Override the temporary directory used by Claude Code |
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | Disable background tasks |
9. Model & Output
| Key | Type | Description |
|---|---|---|
model |
string | Override the default model for all conversations. Examples: claude-sonnet-4-6, claude-opus-4-6. When set at the managed level, users cannot switch to a different model even if they configure one in their personal settings. |
outputStyle |
string | Controls the output style for assistant responses. |
alwaysThinkingEnabled |
boolean | When true, extended thinking is always enabled for every request. Default: false. Uses more tokens but can improve quality on complex tasks. |
skipWebFetchPreflight |
boolean | Skip the WebFetch blocklist check. For enterprise environments with their own restrictive network policies where the built-in blocklist is redundant or causes false positives. |
otelHeadersHelper |
string (path) | Path to a script that outputs OpenTelemetry headers for authentication with your OTEL collector. The script's stdout is used as header values. |
10. General Settings
| Key | Type | Description |
|---|---|---|
cleanupPeriodDays |
integer | How many days to retain local session transcripts. Default: 30. Set lower (e.g., 7) for security-sensitive environments. Minimum: 1. |
autoUpdates |
boolean | Whether automatic updates are enabled. Default: true. Set to false to disable. The DISABLE_AUTOUPDATER env var takes precedence over this. |
includeCoAuthoredBy |
boolean | Whether to include the "co-authored-by Claude" byline in git commits and pull requests. Default: true. Set to false to remove attribution. |
includeGitInstructions |
boolean | Include built-in commit and PR workflow instructions in Claude's system prompt. Default: true. Set to false if you provide your own git workflow via skills or CLAUDE.md. The CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS env var takes precedence. |
spinnerTipsEnabled |
boolean | Show tips in the loading spinner. Default: true. |
verbose |
boolean | Show full bash and command outputs. Default: false. |
11. Company Announcements
| Key | Type | Description |
|---|---|---|
companyAnnouncements |
string[] | Array of messages displayed to all developers at Claude Code startup. Use for policy reminders, security notices, onboarding info, etc. Announcements are shown once at session start — developers in long-running sessions won't see new announcements until they restart. |
12. Tool Names & Pattern Syntax
Permission rules use the format
ToolName or ToolName(pattern). These go into the deny, allow, and ask arrays.
| Tool | Pattern Support | Description |
|---|---|---|
Bash | Bash(command:*) | Execute shell commands. Patterns match the command name and arguments. Bash(curl:*) matches all curl calls. Bash(npm run lint) matches that exact command. Bash alone matches ALL bash calls. |
Read | Read(glob) | Read file contents. Supports gitignore-style patterns. Read(**/.env) matches .env files anywhere. Read(**/*.key) matches all .key files. |
Edit | Edit(glob) | Edit existing files. Same glob syntax as Read. |
Write | Write(glob) | Create new files. Same glob syntax. |
MultiEdit | No patterns | Edit multiple files in one operation. |
WebFetch | WebFetch(domain:x) | Make HTTPS requests. Pattern specifies allowed domain: WebFetch(domain:example.com) |
WebSearch | No patterns | Perform web searches. No arguments — can only be added as-is to deny/allow/ask. |
Glob | No patterns | File pattern matching (find files). |
Grep | No patterns | Search file contents. |
LS | No patterns | List directory contents. |
Task | No patterns | Create and manage subagent tasks. |
TodoWrite | No patterns | Write to Claude's internal todo list. |
NotebookEdit | No patterns | Edit Jupyter notebook cells. |
NotebookRead | No patterns | Read Jupyter notebook cells. |
mcp__servername | No wildcards | Individual MCP tool. Must match the exact tool name as defined in .mcp.json. Does not support wildcards — each tool must be listed individually. |
⚠ Security note on Bash patterns: Bash patterns match the command string but are NOT a full security sandbox. A determined user could potentially circumvent pattern-based Bash restrictions. For true isolation, combine with the sandbox settings and OS-level protections.
13. Settings Precedence & Merge Behavior
Settings are evaluated in strict priority order. Higher-priority settings override lower ones, except for array settings which merge.
| Priority | Source | Notes |
|---|---|---|
| 1 | Server-managed (Claude.ai admin console) | Highest priority. Delivered from Anthropic's servers. Cannot be overridden by anything. |
| 2 | MDM / OS-level policies | macOS plist or Windows HKLM registry. Deployed via Jamf, Kandji, Intune, Group Policy. |
| 3 | managed-settings.json file | System-level file requiring admin privileges. Cannot be overridden by user/project settings. |
| 4 | HKCU registry (Windows only) | Per-user Windows registry. Lowest managed priority — only used when no admin-level source exists. |
| 5 | CLI arguments (--settings) | Temporary settings for a single session. |
| 6 | .claude/settings.local.json | Personal project overrides. Not committed to git. |
| 7 | .claude/settings.json | Team-shared project settings. Committed to git. |
| 8 | ~/.claude/settings.json | Personal global settings. Lowest priority. |
Array merge behavior: Array-valued settings like
permissions.allow, permissions.deny, and sandbox.filesystem.allowWrite are concatenated and deduplicated across scopes — not replaced. Lower-priority scopes can ADD entries but cannot remove entries set by higher-priority scopes.
Within the managed tier, only ONE source is used (they do NOT merge): server-managed > MDM/OS > managed-settings.json > HKCU.
Scalar override behavior: For non-array values (strings, booleans, numbers), higher-priority scopes completely replace lower-priority values. Example: if managed sets
model: "claude-sonnet-4-6", a user's model: "claude-opus-4-6" is ignored.
14. File Paths by OS
| OS | managed-settings.json | managed-mcp.json |
|---|---|---|
| macOS | /Library/Application Support/ClaudeCode/managed-settings.json | /Library/Application Support/ClaudeCode/managed-mcp.json |
| Linux / WSL | /etc/claude-code/managed-settings.json | /etc/claude-code/managed-mcp.json |
| Windows | C:\Program Files\ClaudeCode\managed-settings.json | C:\Program Files\ClaudeCode\managed-mcp.json |
⚠ Deprecated path: The legacy Windows path
C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of Claude Code v2.1.75. Migrate to C:\Program Files\ClaudeCode\.
| OS | MDM / Policy delivery |
|---|---|
| macOS | com.anthropic.claudecode managed preferences domain — deploy via Jamf, Kandji, or other MDM configuration profiles |
| Windows | HKLM\SOFTWARE\Policies\ClaudeCode — REG_SZ or REG_EXPAND_SZ "Settings" value containing JSON. Deploy via Group Policy or Intune. |
| Windows (user) | HKCU\SOFTWARE\Policies\ClaudeCode — lowest managed priority, only used when no admin-level source exists. |
Verify with /status: Run
/status inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer along with its origin (e.g., "Enterprise managed settings (remote)", "Enterprise managed settings (plist)", "Enterprise managed settings (file)").
15. Common Policy Presets
🔒 Maximum Lockdown
Block everything. Users can only read code and plan — no execution, no network, no plugins. IT controls all rules.
{
"allowManagedPermissionRulesOnly": true,
"allowManagedHooksOnly": true,
"strictKnownMarketplaces": [],
"permissions": {
"disableBypassPermissionsMode": "disable",
"defaultMode": "plan",
"deny": ["Bash", "Edit", "Write", "MultiEdit", "WebFetch", "WebSearch"]
},
"disableAllHooks": true
}
⚖ Balanced Enterprise
Deny dangerous commands and sensitive file access. Allow safe read operations. Ask before network access. Sandbox bash with approved domains.
{
"allowManagedPermissionRulesOnly": true,
"allowManagedHooksOnly": true,
"forceLoginMethod": "console",
"forceLoginOrgUUID": "org_your_uuid_here",
"permissions": {
"disableBypassPermissionsMode": "disable",
"deny": [
"Bash(sudo:*)", "Bash(su:*)", "Bash(curl:*)", "Bash(wget:*)",
"Bash(ssh:*)", "Bash(rm -rf:*)", "Bash(git push --force:*)",
"Read(**/.env)", "Read(**/.env.*)", "Read(**/secrets/**)"
],
"allow": ["Read", "Glob", "Grep", "LS", "Bash(git diff:*)", "Bash(git log:*)"],
"ask": ["Bash", "Edit", "Write", "WebFetch", "WebSearch"]
},
"sandbox": {
"network": {
"allowedDomains": ["github.com", "*.npmjs.org", "pypi.org"]
}
},
"cleanupPeriodDays": 14,
"env": { "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1" },
"companyAnnouncements": ["All code requires review before merge."]
}
🟢 Developer-Friendly
Allow most operations, deny only truly dangerous actions. Good for high-trust teams where speed matters.
{
"permissions": {
"disableBypassPermissionsMode": "disable",
"deny": [
"Bash(sudo:*)", "Bash(su:*)", "Bash(rm -rf /)",
"Read(**/.env)", "Read(**/secrets/**)"
],
"allow": [
"Read", "Edit", "Write", "Glob", "Grep", "LS",
"Bash(npm run *)", "Bash(git:*)", "Bash(find:*)"
],
"ask": ["Bash(rm:*)", "Bash(docker:*)", "WebFetch"]
},
"enableAllProjectMcpServers": true,
"cleanupPeriodDays": 30
}