Claude Code settings.json — Scopes, Keys, Permissions

10 min read · Claude Code configuration guide

settings.json is where Claude Code stores its configuration — permissions, environment variables, hooks, the default model, a custom status line. The docs describe it in fragments scattered across several pages, which is why people keep tripping on the same three things: they can't remember which scope wins, they paste keys that belong in a different file, and they guess at the shape of permissions. This guide pulls the pieces together: the four scopes, the precedence order, the keys worth knowing, and the mistakes that silently break your config.

Two adjacent primitives live in their own files and have their own guides. If you're reaching for hooks, see the Claude Code hooks guide — the shape of a hook entry is its own topic. If you're looking for mcpServers, that key does not live in settings.json at all; see the MCP servers guide for where it actually lives.

Where settings.json lives — 4 scopes

Claude Code reads four separate settings.json files and merges them in a fixed order. Each one answers a different question: "what does IT mandate?", "what do I prefer across all my repos?", "what does this team agree on?", "what's just for me in this repo?"

When to use each:

• Managed — an IT or platform team pushes organization-wide policy (denylist rules, forced disableAllHooks) to every machine and doesn't want users overriding it.
• User — your personal defaults across every repo you touch on this machine: preferred model, your hooks, your common allow rules.
• Project — the agreed-upon rules for a repo: which commands the team wants auto-allowed, which are denied, shared env vars, shared hooks.
• Local — your personal overrides inside a repo that shouldn't be committed: a secret env var, a more permissive allow rule just for you, a temporary deny.

Managed settings have per-OS locations: /Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux and WSL, C:\Program Files\ClaudeCode\managed-settings.json on Windows (the legacy C:\ProgramData\ClaudeCode\... path was dropped in v2.1.75). macOS MDM deployments use the com.anthropic.claudecode managed preferences domain; Windows fleets can ship JSON via the HKLM\SOFTWARE\Policies\ClaudeCode registry key under a Settings REG_SZ value. A managed-settings.d/ drop-in directory is merged alphabetically for multi-file deployments.

How scopes interact (precedence)

When the same key appears in multiple scopes, Claude Code resolves it top-down. Highest wins:

• 1. Managed — can't be overridden by anything below.
• 2. Command-line args — flags passed to the claude invocation; session-only.
• 3. Local — .claude/settings.local.json.
• 4. Project — .claude/settings.json.
• 5. User — ~/.claude/settings.json.

Concrete example: if a permission is allow in user settings and deny in project settings, the project deny wins. Teams lock down shared repos without stomping your personal defaults in other projects. Arrays merge across scopes; objects deep-merge; scalars are overridden by the higher-precedence scope.

~/.claude.json is a separate file, not another scope. It holds theme, notification settings, editor mode, OAuth session state, MCP servers for user and local scopes, per-project state, and caches. Putting its keys into settings.json triggers a schema validation error and the config is silently ignored — this is one of the most common footguns on this surface.

A minimal working settings.json

A working file doesn't need much. This is enough to get useful behavior without surprises:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

Field-by-field:

• $schema — a reference to json.schemastore.org/claude-code-settings.json. VS Code, Cursor, and other schema-aware editors pick it up automatically to give you autocomplete on keys and inline validation on typos. It's optional but cheap.
• permissions.allow — rules that skip the "do you want to let Claude run this?" prompt. Match tool invocations by name and optional argument pattern.
• permissions.deny — rules that refuse the tool call outright. Never prompts, never runs. Good place to pre-empt anything that touches secrets or does network fetches you don't want.
• env — environment variables applied to every session Claude Code spawns. Good for tracing flags, API endpoints, or feature toggles you always want on.

Top-level keys worth knowing

The schema has more keys than most people need. The ones that actually come up in practice:

includeCoAuthoredBy is still accepted but deprecated — prefer attribution.commit, which gives you finer control over the commit and PR trailer text.

The permissions key shape

permissions is the one key worth reading closely because it's the one you'll reach for most and its sub-fields have non-obvious semantics.

Rule evaluation order: deny rules first, then ask, then allow. First match wins. That means a broad allow can't accidentally unlock something a specific deny already caught. If you're wiring hooks inside the permissions model, see the hooks guide — hooks is a separate top-level key, not a subkey of permissions.

Common mistakes

• Putting global config keys into settings.json. editorMode, theme, MCP servers for local or user scope — those live in ~/.claude.json, not settings.json. When you put them in the wrong file, schema validation fails and the config is silently ignored. You won't see an obvious error, just your setting not doing anything.
• Using includeCoAuthoredBy. It's deprecated. Use attribution.commit and attribution.pr instead — you get precise control over the trailer text on both commits and PRs.
• Committing .claude/settings.local.json. Claude Code auto-adds this file to .gitignore when it creates it. Adding it manually to the repo breaks the "local-only override" contract and leaks your personal overrides to the whole team.
• Editing settings.json while Claude Code is running. Backups are automatic (5 retained, timestamped), but the running session may use cached values until you restart. For live changes inside an interactive REPL, use the /config command instead — it picks up edits without a restart.
• Assuming user-scope overrides project-scope. It's the opposite. Project wins over user; local wins over both. The mental model is "more specific scope wins", which is the reverse of some other CLI tools you've used.

How to verify a setting is loaded

• Grep the files directly. Text-search the expected scope's file — ~/.claude/settings.json for user, .claude/settings.json for project, .claude/settings.local.json for local — for the key name. If it's not there, it's not being read. This is the only source of truth for "is my key actually in a file Claude Code will load"; everything else is derived from it.
• Run /config inside an interactive Claude Code REPL. Per the live docs, /config opens "a tabbed Settings interface where you can view status information and modify configuration options." Use it to see what values are in effect after precedence resolves. If a key is in a file but not reflected in /config, a higher-precedence scope is shadowing it, or the running session has a cached value and needs a restart.
• Run /status for session context. Per the commands reference, /status opens the Settings interface on the Status tab — it shows version, model, account, and connectivity. Useful for confirming which model is active and which account you're authenticated against, but it is not a settings-file origin tracer.
• Run claude --help. Confirms that any flag or subcommand you're referencing actually exists on your installed version. Schema-level support for a key can lag the CLI flag that sets it.

Frequently asked questions

Two kits that cover the Claude Code + Cursor workflow

settings.json is the control surface, but a real workflow needs the content that fills it — CLAUDE.md templates, slash commands, hooks patterns, allow/deny rules that match your stack. The Claude Code Starter Kit covers that content. The Cursor Rules Kit covers the same problem for teams driving from the IDE instead of the terminal.