D3 · Claude Code › Cluster 2 · Settings & Configuration

2.1 · settings.json & Its Precedence

Enterprise → command-line order

CONCEPT Four scopes of settings.json — plus a policy layer above them

Claude Code is configured through settings.json files that live at different scopes. The same keys can appear in several files; when they conflict, a fixed precedence decides which value wins. From lowest to highest authority:

ScopeFile path (macOS / Linux)Committed to git?Purpose
User~/.claude/settings.jsonNo (personal)Your defaults across every project
Project.claude/settings.jsonYes (shared)Team settings checked into the repo
Local.claude/settings.local.jsonNo (gitignored)Your personal overrides for this repo
Command-line--setting flags on claudeN/ATemporary, one-session overrides
Managed policy/Library/Application Support/ClaudeCode/managed-settings.jsonAdmin-deployedEnterprise policy that cannot be overridden
🔑 On Linux/WSL the managed file is /etc/claude-code/managed-settings.json; on Windows it is C:\Program Files\ClaudeCode\managed-settings.json. The project files use the same relative .claude/ path on every OS.

CONCEPT The precedence order — highest wins

When the same key is set in more than one place, Claude Code resolves it top-down and takes the first match. Memorise this chain for the exam:

Managed policy ▸ Command-line args ▸ Local project (.claude/settings.local.json) ▸ Project (.claude/settings.json) ▸ User (~/.claude/settings.json).

The two ends are the ones people get wrong. Enterprise managed settings sit at the very top — a security admin can deploy a policy that no user, project, or CLI flag can undo. And command-line flags outrank every file, so a -- override on launch beats even a committed project setting for that session.

⚠️ Managed policy does not just "win ties" — it is authoritative. Keys like allowManagedPermissionRulesOnly or disableAllHooks in the managed file can strip abilities from every lower scope entirely.

DIAGRAM Resolving one setting through the stack

flowchart TD Q["Claude Code needs a setting's value"] --> M{"Set in managed
policy file?"} M -->|"yes"| MW["🔴 Use it — final
(enterprise wins, unoverridable)"] M -->|"no"| C{"Passed as a
command-line flag?"} C -->|"yes"| CW["🟠 Use CLI value
(session override)"] C -->|"no"| L{"In .claude/settings.local.json?"} L -->|"yes"| LW["🔵 Use local value"] L -->|"no"| P{"In .claude/settings.json?"} P -->|"yes"| PW["🔵 Use project value"] P -->|"no"| U["🟢 Fall back to
~/.claude/settings.json (user)"] classDef top fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef mid fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef low fill:#cfe2ff,stroke:#3d7bfe,color:#0a3a9a; classDef base fill:#d4edda,stroke:#28a745,color:#155724; class MW top; class CW mid; class LW low; class PW low; class U base;

CODE The same key at three scopes

A user default, a shared project value, and a personal local override — the local file wins over the project file, which wins over the user file (and any managed policy would beat all three).

// ~/.claude/settings.json  — USER scope (your global default)
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "sonnet",
  "includeCoAuthoredBy": true
}

// .claude/settings.json  — PROJECT scope (committed, shared with the team)
{
  "model": "opus",
  "permissions": { "allow": ["Bash(npm run test:*)"] }
}

// .claude/settings.local.json  — LOCAL scope (gitignored, just you)
{
  // beats the project file for YOUR machine only
  "model": "haiku"
}

# A CLI flag would beat even the local file for one session:
# (managed policy, if present, still overrides everything)
$ claude
🔑 Add "$schema": "https://json.schemastore.org/claude-code-settings.json" at the top of any settings file to get key autocomplete and validation in your editor.

TRADE-OFFS Committing project settings vs. keeping them local

✅ Project settings.json (committed)

  • Whole team gets the same permissions, hooks, model
  • Config is reviewed in PRs like any other code
  • New contributors are productive with zero setup

⚠️ settings.local.json (gitignored)

  • Personal tweaks that shouldn't bind the team
  • Auto-gitignored when created — safe for secrets-adjacent config
  • But: invisible to teammates, so drift is easy to miss
Rule of thumb: shared, safe defaults go in .claude/settings.json; anything personal or machine-specific goes in .claude/settings.local.json; anything an org must enforce goes in the managed policy file.

EXAM TRAPS

Trap: "User settings override project settings because they're 'more specific to me'." → Wrong direction. Project beats user; local beats project. User settings are the lowest-priority fallback.
Trap: "A command-line flag can override enterprise managed policy." → No. Managed policy is the single highest scope — it beats CLI args, local, project, and user. It is deployed by admins and cannot be undone by a user.
Trap: "settings.local.json is committed with the project." → It is gitignored by default (auto-added when created). Only settings.json is meant to be committed.
Trap: "There's only one settings file." → There are up to four writable scopes (user, project, local, CLI) plus the managed policy layer above them.

PRACTICE

Q1 · Give the precedence order from highest to lowest authority.

Enterprise managed policy → command-line arguments → local project (.claude/settings.local.json) → project (.claude/settings.json) → user (~/.claude/settings.json).

Q2 · model is opus in the project file and haiku in settings.local.json. Which runs?

haiku. The local file (settings.local.json) sits above the committed project file in precedence, so its value wins on your machine — unless a managed policy or a CLI flag sets the model higher up.

Q3 · An admin wants a permission rule no developer can remove. Where does it go?

In the managed policy file (/Library/Application Support/ClaudeCode/managed-settings.json on macOS, /etc/claude-code/managed-settings.json on Linux). It is the top of the precedence chain and cannot be overridden by user, project, local, or CLI settings.