Skip to main content
Claude Code reads configuration from a layered set of settings sources. Each source overrides the previous one, giving you fine-grained control from user-wide defaults down to per-project and runtime overrides.

​
Settings hierarchy

Settings are loaded from five sources, in order of increasing precedence:
SourceLocationDescription
userSettings~/.claude/settings.jsonGlobal settings for all projects
projectSettings.claude/settings.jsonShared project settings (commit to version control)
localSettings.claude/settings.local.jsonProject-local settings (gitignored)
flagSettings--settings CLI flagSettings passed at launch
policySettingsmanaged-settings.jsonEnterprise-managed settings (always applied)
Later sources override earlier ones. policySettings and flagSettings are always included regardless of the --setting-sources flag.
policySettings (managed settings) always take precedence and cannot be overridden by users. Enterprise administrators use this to enforce organization-wide policy.

​
Settings file format

Settings files are JSON. You can add the JSON Schema reference for editor autocompletion:
settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-opus-4-5",
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

​
The claude config command

Run /config inside a Claude Code session to open the interactive settings UI. This opens the Config tab of the settings panel where you can view and edit all settings interactively.

​
Key settings

Override the default model used by Claude Code.
{ "model": "claude-opus-4-5" }
Configure tool permission rules. See the Permissions page for full details.
{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(git:*)", "FileEdit"],
    "deny": ["Bash(rm -rf:*)"]
  }
}
Sub-fields:
  • allow — permission rules for automatically allowed operations
  • deny — permission rules for automatically denied operations
  • ask — permission rules that always prompt for confirmation
  • defaultMode — default permission mode (default, acceptEdits, bypassPermissions, dontAsk, plan)
  • disableBypassPermissionsMode — set to "disable" to prevent bypass mode
  • additionalDirectories — additional directories to include in the permission scope
Environment variables to inject into every Claude Code session.
{
  "env": {
    "NODE_ENV": "development",
    "MY_API_KEY": "..."
  }
}
Custom shell commands to run before or after tool executions. See the hooks documentation for the full schema.
{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo running bash" }] }]
  }
}
Number of days to retain chat transcripts. Defaults to 30. Setting to 0 disables session persistence entirely — no transcripts are written and existing ones are deleted at startup.
{ "cleanupPeriodDays": 7 }
Whether to include Claude’s co-authored-by attribution in commits and pull requests. Defaults to true. Deprecated — use attribution instead.
Customize attribution text for commits and PRs.
{
  "attribution": {
    "commit": "Co-authored-by: Claude <[email protected]>",
    "pr": ""
  }
}
Set either field to an empty string to hide attribution for that context.
Include built-in commit and PR workflow instructions in Claude’s system prompt. Defaults to true.
Preferred language for Claude responses and voice dictation, e.g. "japanese" or "spanish".
{ "language": "japanese" }
Controls the output style for assistant responses.
{ "outputStyle": "concise" }
Default shell for input-box ! commands. Accepts "bash" or "powershell". Defaults to "bash" on all platforms.
{ "defaultShell": "bash" }
Set to true to disable syntax highlighting in diffs.
When false, extended thinking is disabled. When absent or true, thinking is enabled automatically for supported models.
Persisted effort level for supported models. Accepts "low", "medium", or "high".
{ "effortLevel": "high" }
Whether the file picker respects .gitignore files. Defaults to true. Note that .ignore files are always respected regardless of this setting.
Path to a script that outputs authentication values for the Claude API.
{ "apiKeyHelper": "/usr/local/bin/my-auth-helper" }
When true, disables all hooks and statusLine execution.
Sandbox runtime configuration. See Permissions — Sandbox mode for details.
Git worktree configuration for the --worktree flag.
{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app"]
  }
}
  • symlinkDirectories — directories to symlink from the main repository into worktrees to avoid disk bloat.
  • sparsePaths — directories to include when creating worktrees via git sparse-checkout (cone mode).

​
The --settings flag

Pass settings at launch time without editing a file. You can provide either a path to a JSON file or an inline JSON string. 
claude --settings /path/to/my-settings.json
Settings supplied via --settings are loaded as flagSettings and override user, project, and local settings, but are overridden by policy settings.

​
The --setting-sources flag

By default, Claude Code loads user, project, and local settings. Use --setting-sources to restrict which file-based sources are loaded. policySettings and flagSettings are always included. 
# Load only user settings (skip project and local)
claude --setting-sources user

# Load user and project settings only (skip local)
claude --setting-sources user,project

# Load no file-based settings (only policy and flag)
claude --setting-sources ""
Valid source names: user, project, local.

​
Environment variable overrides

Some behaviors can be controlled through environment variables. Variables relevant to settings:
VariableDescription
CLAUDE_CONFIG_DIROverride the Claude configuration home directory (defaults to ~/.claude)
CLAUDE_CODE_USE_SANDBOXEnable the sandbox runtime for Bash tool execution
CLAUDE_CODE_DISABLE_POLICY_SKILLSDisable loading skills from managed (policy) settings

​
MDM / managed settings

Enterprise administrators can deploy settings through two mechanisms:
1

Base file

Place a managed-settings.json file in the platform-specific managed path. This file provides organization-wide defaults.
2

Drop-in directory

Place additional .json files in the managed-settings.d/ drop-in directory. Files are merged in alphabetical order. Later files take precedence, following the systemd/sudoers convention — separate teams can ship independent policy fragments (e.g. 10-otel.json, 20-security.json) without coordinating edits to a single file.
Both the base file and drop-in files are merged together before being applied as policySettings. Managed settings always take final precedence over all user-editable sources.
Managed settings cannot be overridden by users. Settings such as allowManagedPermissionRulesOnly, allowManagedHooksOnly, and disableBypassPermissionsMode are only effective when placed in managed settings.

​
Enterprise-only settings

The following settings are intended for managed settings and enterprise administrators:
SettingDescription
availableModelsAllowlist of models users can select. If empty array, only the default model is available.
allowedMcpServersEnterprise allowlist of MCP servers. If empty array, no servers are allowed.
deniedMcpServersEnterprise denylist of MCP servers. Denylist takes precedence over allowlist.
allowManagedHooksOnlyWhen true, only hooks from managed settings run.
allowManagedPermissionRulesOnlyWhen true, only permission rules from managed settings are respected.
allowManagedMcpServersOnlyWhen true, allowedMcpServers is only read from managed settings.
strictPluginOnlyCustomizationRestrict customization surfaces to plugins only. Accepts true (all surfaces) or an array of surface names: "skills", "agents", "hooks", "mcp".
disableBypassPermissionsModeSet to "disable" to prevent users from entering bypass permissions mode.
forceLoginMethodForce a login method: "claudeai" for Claude Pro/Max, "console" for Console billing.
forceLoginOrgUUIDOrganization UUID to include in OAuth login.
skipWebFetchPreflightSkip the WebFetch blocklist check for restrictive enterprise network environments.
strictKnownMarketplacesAllowlist of permitted marketplace sources.
blockedMarketplacesBlocklist of forbidden marketplace sources.

Build docs developers (and LLMs) love

Get started for freeTalk to us