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:
| Scope | File path (macOS / Linux) | Committed to git? | Purpose |
|---|---|---|---|
| User | ~/.claude/settings.json | No (personal) | Your defaults across every project |
| Project | .claude/settings.json | Yes (shared) | Team settings checked into the repo |
| Local | .claude/settings.local.json | No (gitignored) | Your personal overrides for this repo |
| Command-line | --setting flags on claude | N/A | Temporary, one-session overrides |
| Managed policy | /Library/Application Support/ClaudeCode/managed-settings.json | Admin-deployed | Enterprise policy that cannot be overridden |
/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:
.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.
allowManagedPermissionRulesOnly or disableAllHooks in the managed file can strip
abilities from every lower scope entirely.DIAGRAM Resolving one setting through the stack
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
"$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
.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
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.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.