Settings files and precedence
Five scopes, one order, and one important exception.
5 min read · Lesson 1 of 11 in this domain
Claude Code reads configuration from several files at once, and the whole system only makes sense once you see what each layer is for. Managed settings are how an organisation enforces policy on a fleet of machines, so they must win. Local settings are your personal, gitignored overrides for one repo, so they beat the shared project file. Project settings are the team's committed defaults. User settings are your cross-project preferences, the weakest because they are the most general. Precedence is not arbitrary — it runs from most specific and most authoritative down to most general.
- Precedence, highest first: managed → command-line arguments → local → project → user.
- Managed settings cannot be overridden — that is the entire point of the scope.
- The exception: permission rules merge across scopes rather than a higher scope replacing a lower one. A deny added at any layer still applies.
- Managed-only controls exist to lock things down:
allowManagedPermissionRulesOnly,allowManagedHooksOnly,allowManagedMcpServersOnly. ~/.claude.jsonis not a settings file in this hierarchy — it holds the OAuth session, MCP server config, and per-project state such as trust settings.
| Scope | Location | Applies to |
|---|---|---|
| Managed | /Library/Application Support/ClaudeCode/managed-settings.json (macOS) /etc/claude-code/managed-settings.json (Linux/WSL) | All users on the machine |
| User | ~/.claude/settings.json | You, every project |
| Project | .claude/settings.json | The team, committed to git |
| Local | .claude/settings.local.json | You, this repo only (gitignored) |
The exception that catches people out. Your project settings allow Bash(git push:*). Your company's managed settings deny it. With ordinary override semantics the higher layer would simply replace the lower one — but permissions merge, so both rules are live and the deny still applies. This is deliberate: if a higher layer could silently drop a lower layer's deny rule, a project could weaken a personal safety rule you had set for yourself. Merging means a deny added anywhere is a deny everywhere.
Assuming permissions override like every other setting. They merge.
Which settings scope wins a conflict?
Precedence runs managed → CLI args → local → project → user.
How do permission rules behave across scopes?
Permissions are the documented exception to normal override semantics.
Practise this domain with 20%%-weighted questions in the study app.
Open in study appSource: Claude Code Docs — Settings · Independent study aid, not affiliated with or endorsed by Anthropic.