Claude Code Settings

Claude Code Settings

Settings are JSON files that change how Claude Code behaves. You can pick a model, add permission rules, turn off a feature, or share the same rules with a whole team. For example, a .claude/settings.json file with { "model": "opus" } makes each session in that project start on Opus.

Marks

Mark	Meaning
✅	A page of the Claude Code docs names it.
🔍	Only the Claude Code bundle names it. No docs page does.
⚠️	The docs and the bundle differ. The row says how.
🧪	It works only behind a flag, a plan, or a server-side switch. The row says which.
❌	It is removed or does nothing in 2.1.303.

A - in the Default column means that neither the docs nor the schema state a default. The Scope column says which settings files may set the key. Any file means the user, project, local, and managed files.

Pages for Each Group of Keys

The managed schema of 2.1.303 lists 184 keys. The user schema lists 162, and the other 22 are managed-only. Each key has a row on one of these pages.

Page	Keys
Core	Compaction, memory, cleanup, shell, files, env, sandbox, updates
Model	Model, effort, thinking, fast mode, cache lifetime, token reminders
Auth	Credential helpers, login rules, API provider limits
Agents and Remote	agent, workflows, background work, Remote Control, peer sessions
Hooks and Plugins	Hooks, plugins, marketplaces, skills, permissions, statusLine, outputStyle
MCP and Channels	MCP servers, claude.ai connectors, channels
UI	Theme, spinner, tui, voice, notices, feedback
Enterprise	How managed policy arrives, version limits
Extra Keys	Keys that the schema omits, and the keys of ~/.claude.json

Where Settings Live

Scope	File	Who it affects
User	~/.claude/settings.json	You, in every project. CLAUDE_CONFIG_DIR moves ~/.claude.
Shared project	.claude/settings.json	Everyone who works in the folder. Commit it so teammates get it.
Project local	.claude/settings.local.json	You, in this project only. Claude Code keeps the file out of git.
Command line	--settings <file-or-json>	One session. It cannot set Managed or Global config keys.
Managed	managed-settings.json and the other managed sources	Everyone your organization deploys it to.
Global config	~/.claude.json	You. Claude Code writes it. It holds sign-in data, MCP servers, per-project state, and a few keys.

Source: Settings Files and Precedence and Explore the .claude Directory.

• Settings files are strict JSON. A comment or a trailing comma is a syntax error.
• Claude Code reads the shared project file from the primary working directory. After /cd, it reads the new directory (v2.1.246 or later).
• In a git repository, the local file lives at the repository root. In a worktree, it lives at the main checkout root.
• Claude Code adds **/.claude/settings.local.json to your global git excludes file when it writes the local file.
• Claude Code watches the files and reloads them. It runs the ConfigChange hook for each change in a settings file.
• Managed settings from MDM or the console reach a running session on a schedule, not on save.
• A cloud session reads only the shared project file and server-managed settings.
• Run /status to see the Setting sources line. Run claude doctor to see the entries that Claude Code dropped.
• The flag --setting-sources <sources> loads only the sources you name (user, project, local).

The bundle names the five sources userSettings, projectSettings, localSettings, flagSettings, and policySettings.

Which Value Wins

The highest level that sets a key wins.

1. Managed settings.
2. Command line (--settings).
3. Project local settings.
4. Shared project settings.
5. User settings.

Environment variables are not a level. Each pair of key and variable decides alone, such as ANTHROPIC_MODEL over model. See Env Vars. Source: Settings Files and Precedence.

How Lists and Model Keys Merge

• List keys such as permissions.allow merge across scopes.
• allowManagedPermissionRulesOnly stops that merge for permission rules.
• fallbackModel is an ordered chain. The whole value comes from the highest scope that sets it.
• modelPicker never merges. The whole value comes from managed settings, --settings, or user settings. Claude Code ignores project and local values (v2.1.242 or later).
• availableModels: a managed list applies as it is. Across the other scopes, the arrays merge.
• modelSettings resolves one model at a time, together with effortLevel.
• Managed env blocks merge per key across admin sources. CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION=1 turns that off (Environment Variables).

Managed Settings

An administrator puts managed settings on a machine in one of these ways. Source: Deploy Managed Settings.

Platform	Where Claude Code looks
macOS	/Library/Application Support/ClaudeCode/managed-settings.json, and the com.anthropic.claudecode managed preferences domain
Linux and WSL	/etc/claude-code/managed-settings.json
Windows	C:\Program Files\ClaudeCode\managed-settings.json, and the registry keys HKLM\SOFTWARE\Policies\ClaudeCode and HKCU\SOFTWARE\Policies\ClaudeCode
WSL on Windows	The Windows sources, only when wslInheritsWindowsSettings is on
All	The managed-settings.d/ folder next to the file, server-managed settings (cached in ~/.claude/remote-settings.json), and the SDK managedSettings option or --managed-settings flag

• Claude Code merges managed-settings.json first, then each *.json file of managed-settings.d/ in alphabetical order. Number the files to set the order, such as 10-telemetry.json.
• managedSourcesBehavior decides how sources combine. first-wins uses the highest source alone. merge deep-merges them.
• parentSettingsBehavior does the same for the SDK parent tier.
• policyHelper and policyHelpers compute managed settings at startup.

Exceptions to Managed Precedence

For a few keys, a lower scope may set a stricter value, and Claude Code honors it over the managed value. Source: Settings Files and Precedence.

Mark	Key	Value Claude Code honors	Where from
✅	disableClaudeAiConnectors, isolatePeerMachines, permissions.blockReadsOutsideWorkingDirectories	true	Any scope
✅	enableArtifact, disableArtifact	enableArtifact: false or disableArtifact: true	Any scope
✅	autoMode.classifyAllShell	true	~/.claude/settings.json or --settings
✅	remoteControlAtStartup	false	.claude/settings.json or .claude/settings.local.json
✅	crossSessionInbound	A stricter value on the ladder accept, hold, refuse	.claude/settings.json or .claude/settings.local.json
✅	useAutoModeDuringPlan, syncClaudeAiSkills, syncClaudeAiPlugins	false	Managed, --settings, ~/.claude/settings.json, or .claude/settings.local.json
✅	maxEffortLevel	The lowest cap (v2.1.267 or later)	Any scope
🔍	modelProposedGoals, feedbackDrafts, availableModelsMatch, askUserQuestionTimeout, dialogExpiry	A strict value	The bundle lists them as keys with a strict value. The docs do not list them here.

An app that runs Claude Code inside itself and sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST is also an exception. Claude Code then takes the model keys of that app over the managed values.

See Also

• Settings Reference lists each key.
• Settings Files and Precedence explains the scopes.
• Deploy Managed Settings is the guide for administrators.
• Env Vars lists the variables that pair with some keys.
• Permissions And Sandbox covers permissions, sandbox, and autoMode.