• October 7, 2026
• 26 min read

Claude Code — Settings Reference¶

Every key Claude Code reads from settings.json (and the few it keeps in ~/.claude.json), grouped by topic: where the key may go, its type, its default and what it does. The list was checked against Claude Code 2.1.293 (October 2026) and the official settings reference: 243 keys, of which 237 are active and 6 are deprecated or removed.

Where Settings Live¶

Managed settings files by OS: /Library/Application Support/ClaudeCode/managed-settings.json (macOS), /etc/claude-code/managed-settings.json (Linux and WSL), C:\Program Files\ClaudeCode\managed-settings.json (Windows). CLAUDE_CONFIG_DIR moves everything under ~/.claude elsewhere.

There is no ~/.claude/settings.local.json: "local" exists only per project.

Precedence¶

Highest first — a key set higher overrides the same key lower:

1. Managed settings — nothing below overrides them.
2. Command line — claude --settings <file-or-json> for one session.
3. Project local — .claude/settings.local.json.
4. Shared project — .claude/settings.json.

5. User — ~/.claude/settings.json.

6. Lists merge instead of overriding: permissions.allow from user, project and local files are combined. Exceptions: fallbackModel and modelPicker take the whole value from the highest source; a managed availableModels replaces lower lists; modelSettings resolves per model.

7. Hooks merge too: lower levels add hooks, they cannot remove managed ones.
8. Environment variables are not a level. Each variable/key pair has its own rule: ANTHROPIC_MODEL beats the model key from any file, and --model beats both.
9. Stricter values win for a few keys even against managed settings, for example disableClaudeAiConnectors: true, enableArtifact: false, isolatePeerMachines: true and a lower maxEffortLevel from any scope.
10. "User / Managed" keys in the tables below are ignored in .claude/settings.json — a cloned repository must not be able to switch them on for you.

Changing and Checking Settings¶

claude --settings ./ci-settings.json -p "run the tests"    # one session, from a file
claude --settings '{"model": "sonnet"}'                    # one session, inline JSON

• /config — interactive menu; writes user settings or ~/.claude.json for you.
• /status — shows which settings sources loaded, including the managed one.
• /permissions, /hooks, /mcp, /model, /effort, /theme, /statusline — focused editors for one area.
• Settings files are watched and reloaded: edits to permissions, hooks or apiKeyHelper reach the running session. A few keys are read only at start — switch model with /model and effort with /effort instead.
• Broken file: invalid JSON or a rejected value opens a Settings Error dialog at startup; a single bad entry (a malformed rule, an unknown hook event) is skipped with a Settings Warning. claude doctor lists everything that was dropped — the only way to see it after a -p run.
• Add "$schema": "https://json.schemastore.org/claude-code-settings.json" at the top of a settings file for autocomplete and validation in the editor.

Scope column legend: Any — user, project, local or managed file; User / Managed — not honoured in .claude/settings.json; User / Local / Managed — not honoured in the shared project file; Managed — only from managed settings; ~/.claude.json — only from the global config file.

Model and responses¶

Which model runs, how hard it thinks, how it answers, and which models an organization allows.

Permission settings¶

What Claude may do without asking. Rules use the Tool(specifier) syntax: Bash(npm run test *), Read(./.env), Edit(src/**), WebFetch(domain:github.com), mcp__github__*. Evaluation order is deny → ask → allow; a deny anywhere wins.

Sandbox settings¶

OS-level isolation for Bash commands and their child processes: Seatbelt on macOS, bubblewrap on Linux and WSL2. Filesystem paths accept prefixes: / absolute, ~/ home, ./ or no prefix relative to the settings file.

Memory and context¶

CLAUDE.md loading, auto memory, compaction, checkpoints, and how much tool output reaches the context.

Interface and terminal¶

How the terminal UI looks and behaves. Most of these are personal: set them with /config or in ~/.claude/settings.json, not in a committed file.

Git and attribution¶

What Claude Code writes into commits and pull requests, and the built-in git instructions.

Hooks and automation¶

Lifecycle hooks and workflows. The hooks format is shown in the recipes.

Plugins and skills¶

Which plugins, marketplaces and skills load, and how an organization restricts them.

MCP¶

Which MCP servers from .mcp.json, claude.ai connectors and managed configuration are allowed to run.

Agents, sessions, and worktrees¶

The default agent, agent teams, background sessions and git worktree isolation.

Remote, desktop, and notifications¶

Remote Control, the desktop app, SSH hosts, push and terminal notifications.

Authentication and providers¶

Credential helpers, login restrictions and API providers (Anthropic, Bedrock, Vertex AI, Foundry, gateways).

Updates and versioning¶

Release channel and version pins.

Tools¶

Restrictions for desktop-only tools: the Browser pane and mobile simulators.

Privacy and telemetry¶

Transcript retention, feedback prompts and WebFetch preflight checks.

Enterprise and managed settings¶

How managed sources combine and refresh, and the external policy helper.

Global config settings¶

These keys live in ~/.claude.json, not in settings.json; Claude Code ignores them anywhere else. /config writes most of them for you.

Deprecated and Removed Keys¶

Recipes¶

Team Project (.claude/settings.json)¶

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(uv run pytest *)", "Bash(uv run ruff *)", "Bash(git diff *)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)", "Bash(curl *)"]
  },
  "env": { "PYTHONDONTWRITEBYTECODE": "1" },
  "attribution": { "commit": "Co-Authored-By: Claude <[email protected]>", "pr": "" },
  "enabledPlugins": { "formatter@acme-tools": true },
  "cleanupPeriodDays": 14
}

Hooks Format¶

Three levels: event → matcher group → handlers. The handler gets the event as JSON on stdin; exit code 2 blocks the action and shows stderr to Claude, 0 lets it proceed, any other code is a non-blocking error.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs uv run ruff format" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

More events, handler types and exit-code rules: Claude Code Hooks & Agent Personas.

Sandboxed Unattended Runs¶

{
  "permissions": { "defaultMode": "acceptEdits" },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": { "denyRead": ["~/.aws/credentials", "~/.ssh"] },
    "network": { "allowedDomains": ["github.com", "*.pypi.org", "files.pythonhosted.org"] }
  }
}

Organization Policy (managed-settings.json)¶

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "deny": ["Read(**/.env)", "Bash(curl *)"]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "availableModels": ["opus", "sonnet"],
  "strictKnownMarketplaces": [{ "source": "github", "repo": "acme-corp/approved-plugins" }],
  "cleanupPeriodDays": 30,
  "requiredMinimumVersion": "2.1.250"
}

Personal Preferences (~/.claude/settings.json)¶

{
  "model": "opus",
  "effortLevel": "high",
  "theme": "auto",
  "editorMode": "vim",
  "language": "ukrainian",
  "spinnerTipsEnabled": false,
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}

See also¶

• Claude Code Best Practices
• Claude Code Hooks & Agent Personas
• Claude Code Advanced Configuration
• Claude Code — Commands Reference
• Official settings reference
• Claude Code — What's New in 2026