Settings

Configure Claude Code behavior through settings files, the claude config command, CLI flags, and environment variables.

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:

Source	Location	Description
userSettings	~/.claude/settings.json	Global settings for all projects
projectSettings	.claude/settings.json	Shared project settings (commit to version control)
localSettings	.claude/settings.local.json	Project-local settings (gitignored)
flagSettings	--settings CLI flag	Settings passed at launch
policySettings	managed-settings.json	Enterprise-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

model

Override the default model used by Claude Code.

{ "model": "claude-opus-4-5" }

permissions

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

env

Environment variables to inject into every Claude Code session.

{
  "env": {
    "NODE_ENV": "development",
    "MY_API_KEY": "..."
  }
}

hooks

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" }] }]
  }
}

cleanupPeriodDays

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 }

includeCoAuthoredBy

Whether to include Claude’s co-authored-by attribution in commits and pull requests. Defaults to true. Deprecated — use attribution instead.

attribution

Customize attribution text for commits and PRs.

{
  "attribution": {
    "commit": "Co-authored-by: Claude <[e-mail]>",
    "pr": ""
  }
}

Set either field to an empty string to hide attribution for that context.

includeGitInstructions

Include built-in commit and PR workflow instructions in Claude’s system prompt. Defaults to true.

language

Preferred language for Claude responses and voice dictation, e.g. "japanese" or "spanish".

{ "language": "japanese" }

outputStyle

Controls the output style for assistant responses.

{ "outputStyle": "concise" }

defaultShell

Default shell for input-box ! commands. Accepts "bash" or "powershell". Defaults to "bash" on all platforms.

{ "defaultShell": "bash" }

syntaxHighlightingDisabled

Set to true to disable syntax highlighting in diffs.

alwaysThinkingEnabled

When false, extended thinking is disabled. When absent or true, thinking is enabled automatically for supported models.

effortLevel

Persisted effort level for supported models. Accepts "low", "medium", or "high".

{ "effortLevel": "high" }

respectGitignore

Whether the file picker respects .gitignore files. Defaults to true. Note that .ignore files are always respected regardless of this setting.

apiKeyHelper

Path to a script that outputs authentication values for the Claude API.

{ "apiKeyHelper": "/usr/local/bin/my-auth-helper" }

disableAllHooks

When true, disables all hooks and statusLine execution.

sandbox

Sandbox runtime configuration. See Permissions — Sandbox mode for details.

worktree

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.

settings file path

claude --settings /path/to/my-settings.json

claude --settings '{"model":"claude-opus-4-5","permissions":{"defaultMode":"acceptEdits"}}'

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:

Variable	Description
CLAUDE_CONFIG_DIR	Override the Claude configuration home directory (defaults to ~/.claude)
CLAUDE_CODE_USE_SANDBOX	Enable the sandbox runtime for Bash tool execution
CLAUDE_CODE_DISABLE_POLICY_SKILLS	Disable 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:

Setting	Description
availableModels	Allowlist of models users can select. If empty array, only the default model is available.
allowedMcpServers	Enterprise allowlist of MCP servers. If empty array, no servers are allowed.
deniedMcpServers	Enterprise denylist of MCP servers. Denylist takes precedence over allowlist.
allowManagedHooksOnly	When true, only hooks from managed settings run.
allowManagedPermissionRulesOnly	When true, only permission rules from managed settings are respected.
allowManagedMcpServersOnly	When true, allowedMcpServers is only read from managed settings.
strictPluginOnlyCustomization	Restrict customization surfaces to plugins only. Accepts true (all surfaces) or an array of surface names: "skills", "agents", "hooks", "mcp".
disableBypassPermissionsMode	Set to "disable" to prevent users from entering bypass permissions mode.
forceLoginMethod	Force a login method: "claudeai" for Claude Pro/Max, "console" for Console billing.
forceLoginOrgUUID	Organization UUID to include in OAuth login.
skipWebFetchPreflight	Skip the WebFetch blocklist check for restrictive enterprise network environments.
strictKnownMarketplaces	Allowlist of permitted marketplace sources.
blockedMarketplaces	Blocklist of forbidden marketplace sources.