Settings

Claude Code reads settings from JSON files at multiple scopes. Settings merge from lowest to highest priority, so more specific scopes override broader ones.

Settings files

Global (user)
Project (shared)
Local (personal project)
Managed (enterprise)

Location: ~/.claude/settings.jsonApplies to every Claude Code session you run, across all projects. This is where you set personal preferences like your preferred model, theme, and cleanup policy.

{
  "model": "claude-opus-4-5",
  "cleanupPeriodDays": 30,
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Location: .claude/settings.json in your project rootChecked into source control. Use this for settings that should apply to everyone working on the project — permission rules, hook configurations, MCP servers, and environment variables.

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)"],
    "deny": ["Bash(rm -rf *)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  }
}

Location: .claude/settings.local.json in your project rootNot checked into source control (automatically added to .gitignore). Use this for personal overrides within a specific project — your own permission preferences or environment variables that shouldn’t be shared.

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Opening settings

Run /config inside any Claude Code session to open the settings UI. This opens the Config tab of the settings panel, where you can browse and edit the currently active settings for each scope. You can also edit the JSON files directly. Claude Code reloads settings automatically when it detects file changes.

Settings precedence

Settings merge from lowest to highest priority. Later sources override earlier ones for scalar values; arrays are concatenated and deduplicated.

Plugin defaults → User settings → Project settings → Local settings → Managed (policy) settings

Managed (policy) settings always take final precedence. An administrator setting permissions.defaultMode to "default" cannot be overridden by users or project files.

Settings reference

model

Type: string | Scope: AnyOverride the default model used by Claude Code. Accepts any model ID supported by your configured provider.

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

permissions

Type: object | Scope: AnyControls which tools Claude can use and in what mode. See Permissions for full documentation on rule syntax.

Field	Type	Description
`allow`	`string[]`	Rules for operations Claude may perform without asking
`deny`	`string[]`	Rules for operations Claude is always blocked from
`ask`	`string[]`	Rules for operations that always prompt for confirmation
`defaultMode`	`string`	Default permission mode: `"default"`, `"acceptEdits"`, `"plan"`, or `"bypassPermissions"`
`disableBypassPermissionsMode`	`"disable"`	Prevent users from entering bypass permissions mode
`additionalDirectories`	`string[]`	Extra directories Claude may access

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run *)", "Bash(git log *)"],
    "deny": ["Bash(curl *)"]
  }
}

hooks

Type: object | Scope: AnyRun custom shell commands before or after tool executions. See Hooks for full documentation.Supported hook events: PreToolUse, PostToolUse, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, PreCompact, PostCompact.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
      }
    ]
  }
}

cleanupPeriodDays

Type: integer (non-negative) | Default: 30 | Scope: AnyNumber of days to retain chat transcripts. Setting to 0 disables session persistence entirely — no transcripts are written and existing ones are deleted at startup.

{ "cleanupPeriodDays": 7 }

env

Type: object | Scope: AnyEnvironment variables to inject into every Claude Code session. Values are coerced to strings.

{
  "env": {
    "NODE_ENV": "development",
    "MY_API_URL": "https://api.example.com"
  }
}

availableModels

Type: string[] | Scope: ManagedEnterprise allowlist of models users can select. Accepts family aliases ("opus" allows any Opus version), version prefixes, or full model IDs. If undefined, all models are available. If an empty array, only the default model is available.

{ "availableModels": ["claude-opus-4-5", "claude-sonnet-4"] }

allowedMcpServers / deniedMcpServers

Type: object[] | Scope: AnyEnterprise allowlist and denylist for MCP servers. Each entry must have exactly one of serverName, serverCommand, or serverUrl. The denylist takes precedence — if a server matches both lists, it is blocked.

{
  "allowedMcpServers": [
    { "serverName": "my-db-server" },
    { "serverUrl": "https://mcp.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverCommand": ["npx", "malicious-server"] }
  ]
}

worktree

Type: object | Scope: AnyConfiguration for --worktree flag behavior.

Field	Type	Description
`symlinkDirectories`	`string[]`	Directories to symlink from the main repo into worktrees (e.g., `"node_modules"`)
`sparsePaths`	`string[]`	Paths to check out in sparse mode, for faster worktrees in large monorepos

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["src/", "packages/my-service/"]
  }
}

attribution

Type: object | Scope: AnyCustomize the attribution text Claude appends to commits and pull request descriptions.

Field	Type	Description
`commit`	`string`	Attribution text (including any git trailers). Empty string removes attribution.
`pr`	`string`	Attribution text for PR descriptions. Empty string removes attribution.

{
  "attribution": {
    "commit": "Co-Authored-By: Claude <[email protected]>",
    "pr": ""
  }
}

language

Type: string | Scope: AnyPreferred language for Claude responses and voice dictation. Accepts plain language names.

{ "language": "japanese" }

sandbox

Type: object | Scope: AnySandbox configuration for isolating Claude’s tool executions. Contact your administrator for sandbox setup details.

alwaysThinkingEnabled

Type: boolean | Default: true | Scope: AnyWhen false, extended thinking is disabled. When absent or true, thinking is enabled automatically for models that support it.

{ "alwaysThinkingEnabled": false }

effortLevel

Type: "low" | "medium" | "high" | Scope: AnyPersisted effort level for models that support adjustable thinking budgets.

{ "effortLevel": "high" }

autoMemoryEnabled

Type: boolean | Scope: User, localEnable or disable auto-memory for this project. When false, Claude does not read from or write to the auto-memory directory.

{ "autoMemoryEnabled": false }

autoMemoryDirectory

Type: string | Scope: User, localCustom path for auto-memory storage. Supports ~/ for home directory expansion. Ignored if set in project settings (.claude/settings.json) for security reasons. Defaults to ~/.claude/projects/<sanitized-cwd>/memory/.

{ "autoMemoryDirectory": "~/my-memory-store" }

claudeMdExcludes

Type: string[] | Scope: AnyGlob patterns or absolute paths of CLAUDE.md files to exclude from loading. Patterns are matched against absolute paths using picomatch. Only applies to User, Project, and Local memory types — Managed files cannot be excluded.

{
  "claudeMdExcludes": [
    "/home/user/monorepo/vendor/CLAUDE.md",
    "**/third-party/.claude/rules/**"
  ]
}

disableAllHooks

Type: boolean | Scope: AnySet to true to disable all hook and statusLine execution.

{ "disableAllHooks": true }

respectGitignore

Type: boolean | Default: true | Scope: AnyWhether the file picker respects .gitignore files. .ignore files are always respected regardless of this setting.

{ "respectGitignore": false }

defaultShell

Type: "bash" | "powershell" | Default: "bash" | Scope: AnyDefault shell for ! commands in the input box.

{ "defaultShell": "powershell" }

forceLoginMethod

Type: "claudeai" | "console" | Scope: ManagedForce a specific login method. Use "claudeai" for Claude Pro/Max accounts, or "console" for Anthropic Console billing.

{ "forceLoginMethod": "console" }

apiKeyHelper

Type: string | Scope: User, managedPath to a script that outputs authentication values. The script is called to retrieve credentials dynamically instead of reading a static API key.

{ "apiKeyHelper": "/usr/local/bin/get-claude-key.sh" }

syntaxHighlightingDisabled

Type: boolean | Scope: AnyDisable syntax highlighting in diffs.

{ "syntaxHighlightingDisabled": true }

prefersReducedMotion

Type: boolean | Scope: AnyReduce or disable animations (spinner shimmer, flash effects, etc.) for accessibility.

{ "prefersReducedMotion": true }

Managed settings (enterprise)

Administrators can push settings to all users via platform-native mechanisms. Managed settings take precedence over all user and project settings.

macOS
Windows
File-based

Deploy a plist file to /Library/Preferences/ or via MDM (Jamf, Kandji, etc.) targeting com.anthropic.claudecode.

Write settings to the HKLM\Software\Anthropic\Claude Code registry key (machine-wide) or HKCU\Software\Anthropic\Claude Code (per-user, lower priority than HKLM).

Place a managed-settings.json file at the platform-specific managed path. For drop-in configuration fragments, create a managed-settings.d/ directory alongside it. Files in that directory are sorted alphabetically and merged on top of the base file — later filenames win.

managed-settings.json          # base settings (lowest precedence)
managed-settings.d/
  10-security.json             # merged first
  20-model-policy.json         # merged second (wins over 10-)

This convention matches systemd/sudoers drop-ins: independent teams can ship policy fragments without coordinating edits to a single file.

The following managed-only settings lock down user customization surfaces:

Setting	Description
`allowManagedHooksOnly`	When `true`, only hooks defined in managed settings run. User, project, and local hooks are ignored.
`allowManagedPermissionRulesOnly`	When `true`, only permission rules from managed settings are respected.
`allowManagedMcpServersOnly`	When `true`, the `allowedMcpServers` allowlist is only read from managed settings.
`strictPluginOnlyCustomization`	Lock specific customization surfaces (`"skills"`, `"agents"`, `"hooks"`, `"mcp"`) to plugin-only sources. Pass `true` to lock all four, or an array of surface names.

allowManagedPermissionRulesOnly ignores permission rules from user settings, project settings, local settings, and CLI arguments. Make sure your managed rules are comprehensive before enabling this.

JSON schema

Add $schema to your settings file for editor autocompletion and validation:

{
  "$schema": "https://schemas.anthropic.com/claude-code/settings.json"
}

Get Started

Core Concepts

Guides

Configuration

Settings files

Opening settings

Settings precedence

Settings reference

Managed settings (enterprise)

JSON schema

Get Started

Core Concepts

Guides

Configuration

​Settings files

​Opening settings

​Settings precedence

​Settings reference

​Managed settings (enterprise)

​JSON schema

Settings files

Opening settings

Settings precedence

Settings reference

Managed settings (enterprise)

JSON schema