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 when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.

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

Scope	Location	Who it affects	Shared with team?
Managed	Server-managed settings, plist / registry, or system-level managed-settings.json	All users on the machine	Yes (deployed by IT)
User	~/.claude/ directory	You, across all projects	No
Project	.claude/ in repository	All collaborators on this repository	Yes (committed to git)
Local	.claude/settings.local.json	You, in this repository only	No (gitignored)

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

For example, if your user settings set spinnerTipsEnabled to true and project settings set it to false, the project value applies. Permission rules behave differently because they merge across scopes rather than override.

What uses scopes

Feature	User location	Project location	Local location
Settings	~/.claude/settings.json	.claude/settings.json	.claude/settings.local.json
Subagents	~/.claude/agents/	.claude/agents/	None
MCP servers	~/.claude.json	.mcp.json	~/.claude.json (per-project)
Plugins	~/.claude/settings.json	.claude/settings.json	.claude/settings.local.json
CLAUDE.md	~/.claude/CLAUDE.md	CLAUDE.md or .claude/CLAUDE.md	CLAUDE.local.md

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

  • Server-managed settings: delivered from Anthropic's servers via the Claude.ai admin console.

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

    • macOS: com.anthropic.claudecode managed preferences domain
    • Windows: HKLM\SOFTWARE\Policies\ClaudeCode registry key
    • Windows (user-level): HKCU\SOFTWARE\Policies\ClaudeCode

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

    File-based managed settings also support a drop-in directory at managed-settings.d/ in the same system directory alongside managed-settings.json.

    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.

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

Claude Code automatically creates timestamped backups of configuration files and retains the five most recent backups to prevent data loss.

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

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

Available settings

settings.json supports a number of options:

Key	Description	Example
agent	Run the main thread as a named subagent	"code-reviewer"
allowedChannelPlugins	(Managed) Allowlist of channel plugins that may push messages	[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]
allowedHttpHookUrls	Allowlist of URL patterns that HTTP hooks may target	["https://hooks.example.com/*"]
allowedMcpServers	When set in managed-settings.json, allowlist of MCP servers users can configure	[{ "serverName": "github" }]
allowManagedHooksOnly	(Managed) Only managed hooks, SDK hooks, and force-enabled plugin hooks are loaded	true
allowManagedMcpServersOnly	(Managed) Only admin-defined allowlist of MCP servers applies	true
allowManagedPermissionRulesOnly	(Managed) Only rules in managed settings apply	true
alwaysThinkingEnabled	Enable extended thinking by default for all sessions	true
apiKeyHelper	Custom script to generate an auth value	/bin/generate_temp_api_key.sh
attribution	Customize attribution for git commits and pull requests	{"commit": "... Generated with Claude Code", "pr": ""}
autoMemoryDirectory	Custom directory for auto memory storage	"~/my-memory-dir"
autoMemoryEnabled	Enable auto memory	false
autoMode	Customize what the auto mode classifier blocks and allows	{"soft_deny": ["$defaults", "Never run terraform apply"]}
autoScrollEnabled	In fullscreen rendering, follow new output to the bottom	false
autoUpdatesChannel	Release channel to follow for updates	"stable"
availableModels	Restrict which models users can select	["sonnet", "haiku"]
awaySummaryEnabled	Show a one-line session recap when you return after a few minutes away	true
awsAuthRefresh	Custom script that modifies the .aws directory	aws sso login --profile myprofile
awsCredentialExport	Custom script that outputs JSON with AWS credentials	/bin/generate_aws_grant.sh
blockedMarketplaces	(Managed) Blocklist of marketplace sources	[{ "source": "github", "repo": "untrusted/plugins" }]
channelsEnabled	(Managed) Allow channels for the organization	true
claudeMd	(Managed) CLAUDE.md-style instructions injected as organization-managed memory	"Always run make lint before committing."
claudeMdExcludes	Glob patterns or absolute paths of CLAUDE.md files to skip	["**/vendor/**/CLAUDE.md"]
cleanupPeriodDays	Session files older than this period are deleted at startup (default: 30)	20
companyAnnouncements	Announcement to display to users at startup	["Welcome to Acme Corp!"]
defaultShell	Default shell for input-box ! commands	"powershell"
deniedMcpServers	(Managed) Denylist of MCP servers explicitly blocked	[{ "serverName": "filesystem" }]
disableAgentView	Turn off background agents and agent view	true
disableAllHooks	Disable all hooks and custom status line	true
disableAutoMode	Prevent auto mode from being activated	"disable"
disableDeepLinkRegistration	Prevent registering the claude-cli:// protocol handler	"disable"
disabledMcpjsonServers	List of specific MCP servers from .mcp.json files to reject	["filesystem"]
disableRemoteControl	Disable Remote Control (min v2.1.128)	true
disableSkillShellExecution	Disable inline shell execution for skills and custom commands	true
editorMode	Key binding mode for the input prompt	"vim"
effortLevel	Persist the effort level across sessions	"xhigh"
enableAllProjectMcpServers	Automatically approve all MCP servers defined in project .mcp.json	true
enabledMcpjsonServers	List of specific MCP servers from .mcp.json to approve	["memory", "github"]
env	Environment variables applied to every session and subprocesses	{"FOO": "bar"}
fastModePerSessionOptIn	When true, fast mode does not persist across sessions	true
feedbackSurveyRate	Probability (0-1) that the session quality survey appears	0.05
fileSuggestion	Configure a custom script for @ file autocomplete	{"type": "command", "command": "~/.claude/file-suggestion.sh"}
forceLoginMethod	Restrict login to claudeai or console	claudeai
forceLoginOrgUUID	Require login to belong to a specific organization	"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
forceRemoteSettingsRefresh	(Managed) Block CLI startup until remote managed settings are freshly fetched	true
gcpAuthRefresh	Custom script that refreshes GCP Application Default Credentials	gcloud auth application-default login
hooks	Configure custom commands to run at lifecycle events	See hooks docs
httpHookAllowedEnvVars	Allowlist of environment variable names HTTP hooks may interpolate	["MY_TOKEN", "HOOK_SECRET"]
includeCoAuthoredBy	Deprecated: Use attribution instead	false
includeGitInstructions	Include built-in commit and PR workflow instructions in system prompt	false
language	Configure Claude's preferred response language	"japanese"
maxSkillDescriptionChars	Per-skill character cap on description text (min v2.1.105)	2048
minimumVersion	Floor that prevents installing a version below this one	"2.1.100"
model	Override the default model to use	"claude-sonnet-4-6"
modelOverrides	Map Anthropic model IDs to provider-specific model IDs	{"claude-opus-4-6": "arn:aws:bedrock:..."}
otelHeadersHelper	Script to generate dynamic OpenTelemetry headers	/bin/generate_otel_headers.sh
outputStyle	Configure an output style to adjust the system prompt	"Explanatory"
parentSettingsBehavior	(Managed) Controls parent-supplied settings behavior (min v2.1.133)	"merge"
permissions	Permission rules structure	See table below
plansDirectory	Customize where plan files are stored	"./plans"
pluginTrustMessage	(Managed) Custom message appended to plugin trust warning	"All plugins from our marketplace are approved by IT"
policyHelper	Admin-deployed executable that computes managed settings dynamically (min v2.1.136)	{"path": "/usr/local/bin/claude-policy"}
preferredNotifChannel	Method for task-complete and permission-prompt notifications	"terminal_bell"
prefersReducedMotion	Reduce or disable UI animations for accessibility	true
prUrlTemplate	URL template for the PR badge	"https://reviews.example.com/{owner}/{repo}/pull/{number}"
respectGitignore	Control whether the @ file picker respects .gitignore patterns	false
showClearContextOnPlanAccept	Show the "clear context" option on plan accept screen	true
showThinkingSummaries	Show extended thinking summaries in interactive sessions	true
showTurnDuration	Show turn duration messages after responses	false
skillListingBudgetFraction	Fraction of context window reserved for skill listing (min v2.1.105)	0.02
skillOverrides	Per-skill visibility overrides (min v2.1.129)	{"legacy-context": "name-only", "deploy": "off"}
skipWebFetchPreflight	Skip the WebFetch domain safety check	true
spinnerTipsEnabled	Show tips in the spinner while Claude is working	false
spinnerTipsOverride	Override spinner tips with custom strings	{ "excludeDefault": true, "tips": ["Use our internal tool X"] }
spinnerVerbs	Customize the action verbs shown while a turn is in progress	{"mode": "append", "verbs": ["Pondering", "Crafting"]}
sshConfigs	SSH connections to show in Desktop environment dropdown	[{"id": "dev-vm", "name": "Dev VM", "sshHost": "user@dev.example.com"}]
statusLine	Configure a custom status line to display context	{"type": "command", "command": "~/.claude/statusline.sh"}
strictKnownMarketplaces	(Managed) Allowlist of plugin marketplace sources	[{ "source": "github", "repo": "acme-corp/plugins" }]
syntaxHighlightingDisabled	Disable syntax highlighting in diffs, code blocks, and file previews	true
teammateMode	How agent team teammates display	"in-process"
terminalProgressBarEnabled	Show the terminal progress bar in supported terminals	false
tui	Terminal UI renderer	"fullscreen"
useAutoModeDuringPlan	Whether plan mode uses auto mode semantics when available	false
viewMode	Default transcript view mode on startup	"verbose"
voice	Voice dictation settings	{ "enabled": true, "mode": "tap" }
voiceEnabled	Legacy alias for voice.enabled	true
wslInheritsWindowsSettings	(Windows managed) WSL reads managed settings from Windows policy chain	true

Global config settings

These settings are stored in ~/.claude.json rather than settings.json. Adding them to settings.json will trigger a schema validation error.

Key	Description	Example
autoConnectIde	Automatically connect to a running IDE when starting from external terminal	true
autoInstallIdeExtension	Automatically install the Claude Code IDE extension when running from a VS Code terminal	false
externalEditorContext	Prepend Claude's previous response as #-commented context when opening external editor with Ctrl+G	true
teammateDefaultModel	Default model for agent team teammates when spawn prompt doesn't specify one	"sonnet"

Worktree settings

Configure how --worktree creates and manages git worktrees.

Key	Description	Example
worktree.baseRef	Which ref new worktrees branch from ("fresh" or "head")	"head"
worktree.symlinkDirectories	Directories to symlink from main repository into each worktree	["node_modules", ".cache"]
worktree.sparsePaths	Directories to check out via git sparse-checkout	["packages/my-app", "shared/utils"]
worktree.bgIsolation	Isolation mode for background sessions (min v2.1.143)	"none"

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

Permission settings

Keys	Description	Example
allow	Array of permission rules to allow tool use	[ "Bash(git diff *)" ]
ask	Array of permission rules to ask for confirmation	[ "Bash(git push *)" ]
deny	Array of permission rules to deny tool use	[ "WebFetch", "Bash(curl *)", "Read(./.env)" ]
additionalDirectories	Additional working directories for file access	[ "../docs/" ]
defaultMode	Default permission mode when opening Claude Code	"acceptEdits"
disableBypassPermissionsMode	Prevent bypassPermissions mode from being activated	"disable"
skipDangerousModePermissionPrompt	Skip confirmation prompt before entering bypass permissions mode	true

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 matching rule wins.

Rule	Effect
Bash	Matches all Bash commands
Bash(npm run *)	Matches commands starting with npm run
Read(./.env)	Matches reading the .env file
WebFetch(domain:example.com)	Matches fetch requests to example.com

Sandbox settings

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

Keys	Description	Example
enabled	Enable bash sandboxing (macOS, Linux, and WSL2)	true
failIfUnavailable	Exit with error at startup if sandbox cannot start	true
autoAllowBashIfSandboxed	Auto-approve bash commands when sandboxed	true
excludedCommands	Commands that should run outside of the sandbox	["docker *"]
allowUnsandboxedCommands	Allow commands to run outside the sandbox via dangerouslyDisableSandbox parameter	false
filesystem.allowWrite	Additional paths where sandboxed commands can write	["/tmp/build", "~/.kube"]
filesystem.denyWrite	Paths where sandboxed commands cannot write	["/etc", "/usr/local/bin"]
filesystem.denyRead	Paths where sandboxed commands cannot read	["~/.aws/credentials"]
filesystem.allowRead	Paths to re-allow reading within denyRead regions	["."]
filesystem.allowManagedReadPathsOnly	(Managed) Only managed allowRead paths are respected	true
network.allowUnixSockets	(macOS only) Unix socket paths accessible in sandbox	["~/.ssh/agent-socket"]
network.allowAllUnixSockets	Allow all Unix socket connections in sandbox	true
network.allowLocalBinding	Allow binding to localhost ports (macOS only)	true
network.allowMachLookup	Additional XPC/Mach service names the sandbox may look up (macOS only)	["com.apple.coresimulator.*"]
network.allowedDomains	Array of domains to allow for outbound network traffic	["github.com", "*.npmjs.org"]
network.deniedDomains	Array of domains to block for outbound network traffic	["sensitive.cloud.example.com"]
network.allowManagedDomainsOnly	(Managed) Only managed allowedDomains are respected	true
network.httpProxyPort	HTTP proxy port	8080
network.socksProxyPort	SOCKS5 proxy port	8081
enableWeakerNestedSandbox	Enable weaker sandbox for unprivileged Docker environments	true
enableWeakerNetworkIsolation	(macOS only) Allow access to system TLS trust service in sandbox	true
bwrapPath	(Managed, Linux/WSL2) Absolute path to bubblewrap binary	/opt/admin/bwrap
socatPath	(Managed, Linux/WSL2) Absolute path to socat binary	/opt/admin/socat

Sandbox path prefixes

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

Prefix	Meaning	Example
/	Absolute path from filesystem root	/tmp/build stays /tmp/build
~/	Relative to home directory	~/.kube becomes $HOME/.kube
./ or no prefix	Relative to project root for project settings, or to ~/.claude for user settings	./output in .claude/settings.json resolves to <project-root>/output

Configuration example:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "*.example.com"]
    }
  }
}

Windows sandbox settings

Claude Code does not currently support sandboxing on native Windows. The sandbox settings documented above apply to macOS, Linux, and WSL2 only.

Attribution settings

Customize attribution for git commits and pull requests:

Key	Description	Example
attribution.commit	Footer added to Claude-generated commits. Set to "" to suppress entirely	"... Generated with Claude Code"
attribution.pr	Footer added to Claude-generated pull requests. Set to "" to suppress entirely	"Created with Claude Code"

{
  "attribution": {
    "commit": "... Generated with Claude Code",
    "pr": "Created with Claude Code"
  }
}

File suggestion settings

Configure a custom script for @ file autocomplete:

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

The script receives the partial path as $1 and should output one suggestion per line.

Hook configuration

Configure custom commands to run at lifecycle events. See the hooks documentation for format and available events.

Settings precedence

Settings are merged across scopes in this priority order:

1. Managed (highest priority)
2. Command line arguments
3. Local
4. Project
5. User (lowest priority)

Permission rules merge across scopes rather than override — all allow, ask, and deny rules from all scopes are combined. Managed settings can use allowManagedPermissionRulesOnly to restrict which scopes can define permission rules.

Compute managed settings with a policy helper

The policyHelper setting (min v2.1.136) specifies an admin-deployed executable that computes managed settings dynamically at startup. Only honored from MDM or a system managed-settings.json file. The executable should output JSON to stdout matching the managed settings format.

{
  "policyHelper": {
    "path": "/usr/local/bin/claude-policy"
  }
}

The policy helper runs at startup and its output is merged with static managed settings, with the policy helper's output taking precedence.