Skip to main content
Claude Code loads settings from multiple sources and merges them in priority order. Understanding which file controls what allows you to apply the right scope — personal preferences globally, shared norms per repo, and sensitive or ephemeral overrides locally.

​
Settings files

User settings

~/.claude/settings.jsonApplies to every Claude Code session for your account. Suitable for personal defaults like preferred model, effort level, or shell.

Project settings

.claude/settings.jsonChecked into the repository. Shared with your team. Use for project-wide permissions, MCP servers, and hooks.

Local settings

.claude/settings.local.jsonGitignored automatically. Per-developer overrides that should not be committed (e.g. personal API keys or local tool paths).

Policy settings

Managed via MDM / managed-settings.jsonSet by enterprise administrators. Always wins. Users cannot override policy settings.

​
Precedence order

When the same key appears in multiple files, the later source wins: 
userSettings → projectSettings → localSettings → flagSettings → policySettings
Policy settings (enterprise MDM) always take final precedence regardless of what users or projects specify.

​
JSON Schema

Add $schema to any settings file for editor autocompletion and validation:
settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

​
All configuration options

​
Authentication

Path to a script that outputs authentication values. Claude Code executes this script and uses its stdout as the API key.
{
  "apiKeyHelper": "/usr/local/bin/get-api-key.sh"
}
Path to a script that exports AWS credentials for use with Amazon Bedrock.
{
  "awsCredentialExport": "~/.claude/scripts/aws-creds.sh"
}
Path to a script that refreshes AWS authentication.
Command to refresh GCP authentication.
{
  "gcpAuthRefresh": "gcloud auth application-default login"
}
Force a specific login method. "claudeai" for Claude Pro/Max, "console" for Console billing.
{
  "forceLoginMethod": "claudeai"
}
Organization UUID to use for OAuth login. Appended as a URL parameter to the authorization URL.

​
Model and inference

Override the default model. Accepts a full model ID or an alias (sonnet, opus, haiku, best).
{
  "model": "claude-sonnet-4-6"
}
Persisted effort level for supported models. Accepted values: "low", "medium", "high". Affects how much the model thinks before responding.
{
  "effortLevel": "medium"
}
"max" effort is Opus 4.6 only and is session-scoped for external users — it is not persisted to settings.
Enterprise allowlist of models users may select. Accepts family aliases ("opus"), version prefixes ("opus-4-5"), and full model IDs. An empty array restricts users to only the default model.
{
  "availableModels": ["sonnet", "claude-sonnet-4-6"]
}
Map Anthropic model IDs to provider-specific IDs (e.g. Amazon Bedrock inference profile ARNs). Typically used in managed settings.
{
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-6-v1"
  }
}
When false, thinking (extended reasoning) is disabled entirely. When absent or true, thinking is enabled automatically for models that support it.
Enable fast mode. When true, Claude routes certain requests to a faster, lighter model.
When true, fast mode does not persist across sessions. Each new session starts with fast mode off.
Override the model used for server-side advisor tool calls.

​
Permissions

Configure tool usage permissions with allow, deny, and ask rule lists.
{
  "permissions": {
    "allow": ["Bash(git *)", "Read(*.ts)"],
    "deny": ["Bash(rm -rf *)"],
    "ask": ["Write(*.prod.*)"],
    "defaultMode": "acceptEdits"
  }
}
Permission rules use the syntax ToolName(pattern). The defaultMode controls what happens when no rule matches.
When true (and set in managed settings), only allow/deny/ask rules from managed settings are respected. User, project, local, and CLI argument rules are ignored.
Set to "disable" to prevent users from enabling bypass permissions mode.
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

​
Hooks

Define lifecycle hooks that run shell commands, LLM prompts, HTTP requests, or sub-agents in response to tool events. See the Hooks page for full reference.
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}
When true, disables all hooks and statusLine execution.
When true (set in managed settings only), only hooks from managed settings run. User, project, and local hooks are ignored.
Allowlist of URL patterns that HTTP hooks may target. Supports * as a wildcard. When set, HTTP hooks with non-matching URLs are blocked.
{
  "allowedHttpHookUrls": ["https://hooks.example.com/*"]
}
Allowlist of environment variable names that HTTP hooks may interpolate into headers.
{
  "httpHookAllowedEnvVars": ["MY_AUTH_TOKEN", "WEBHOOK_SECRET"]
}

​
Environment variables

Environment variables injected into every Claude Code session.
{
  "env": {
    "NODE_ENV": "development",
    "ANTHROPIC_API_KEY": "sk-..."
  }
}

​
MCP servers

Automatically approve all MCP servers declared in .mcp.json.
Enterprise allowlist of MCP servers. Accepts entries matching by serverName, serverCommand, or serverUrl. When set, only listed servers are permitted.
{
  "allowedMcpServers": [
    { "serverName": "filesystem" },
    { "serverUrl": "https://mcp.example.com/*" }
  ]
}
Enterprise denylist of MCP servers. Denylist takes precedence over allowlist.
{
  "deniedMcpServers": [
    { "serverName": "untrusted-server" }
  ]
}
When true (set in managed settings), allowedMcpServers is only read from managed settings. Users can still add their own servers, but only the admin-defined allowlist applies.

​
Git and attribution

Customize attribution text appended to commits and pull requests.
{
  "attribution": {
    "commit": "Co-authored-by: Claude <noreply@anthropic.com>",
    "pr": ""
  }
}
Set either field to an empty string "" to suppress attribution entirely for that surface.
Include built-in commit and PR workflow instructions in Claude’s system prompt. Defaults to true.
Git worktree configuration for the --worktree flag.
{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["src", "packages/core"]
  }
}
symlinkDirectories avoids disk bloat by symlinking shared directories from the main repository. sparsePaths uses git sparse-checkout (cone mode) to check out only the listed paths — dramatically faster in large monorepos.

​
UI and appearance

Preferred language for Claude responses and voice dictation.
{
  "language": "japanese"
}
Controls the output style for assistant responses.
Disable syntax highlighting in diffs.
Reduce or disable animations (spinner shimmer, flash effects, etc.) for accessibility.
Display a custom status line rendered by a shell command.
{
  "statusLine": {
    "type": "command",
    "command": "~/scripts/my-status.sh",
    "padding": 2
  }
}
Customize the action verbs shown in the spinner.
{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["deploying", "terraforming"]
  }
}
mode: "append" adds to the defaults; "replace" uses only your verbs.
When true (default), /rename updates the terminal tab title.

​
Memory and sessions

Number of days to retain chat transcripts. Default is 30. Setting to 0 disables session persistence entirely — no transcripts are written and existing ones are deleted at startup.
{
  "cleanupPeriodDays": 7
}
Enable auto-memory for the project. When false, Claude will not read from or write to the auto-memory directory.
Custom directory for auto-memory storage. Supports ~/ prefix. Ignored if set in project settings for security. Defaults to ~/.claude/projects/<sanitized-cwd>/memory/.
Custom directory for plan files, relative to project root. Defaults to ~/.claude/plans/.
Glob patterns or absolute paths of CLAUDE.md files to exclude from loading.
{
  "claudeMdExcludes": ["**/vendor/**", "/home/user/monorepo/CLAUDE.md"]
}

​
Enterprise controls

Lock customization surfaces so only plugins (not user/project files) can provide them. Accepts true (lock all four surfaces), false (explicit no-op), or an array of surface names: "skills", "agents", "hooks", "mcp".
{
  "strictPluginOnlyCustomization": ["hooks", "mcp"]
}
Release channel for auto-updates. Either "latest" or "stable".
Minimum version to stay on — prevents downgrades when switching to the stable channel.
An array of announcement strings to display at startup (one is randomly selected).
{
  "companyAnnouncements": [
    "Our internal MCP server has been updated — run /mcp to reconnect."
  ]
}
Skip the WebFetch blocklist check for enterprise environments with restrictive security policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us