Settings layers
The order in which combines settings files. See what it is, how it works, how it is used and what to watch for, with pictures and examples.
What it is
can find the same setting in several places, so it needs a fixed order to decide which value wins. From highest to lowest, the layers are managed settings, the --settings flag, .claude/settings.local.json, .claude/settings.json, and ~/.claude/settings.json. When two layers set the same single value, such as a name, the higher layer wins. When they set the same list, such as permissions.allow, Claude Code joins the lists so each file can add entries without removing others. This lets an organization, a team and each person all have a say without fighting over one file.
How it works
-
Claude Code reads every
-
Higher layer wins for single values
-
Lists from all layers are joined
-
See loaded files with /status
How to use it
-
~/.claude/settings.jsonyour personal defaults for every project. It is the lowest layer.
-
.claude/settings.jsonthe team file you to . In that project it beats your user file.
-
.claude/settings.local.jsonyour own override for one project. It beats the team file and stays out of your commits.
-
claude --settings '{"spinnerTipsEnabled": true}'sets a key for this one session only, above every file except managed settings.
Watch out
Environment variables are not a layer. For example, ANTHROPIC_MODEL in your wins over the model key in any file. A few keys accept a stricter value from a lower layer even when managed settings say otherwise, and a few list keys such as fallbackModel are taken whole instead of joined.
Related terms
Original and official docs
This page explains the term in plain words. The original is the authority: if they differ, follow the original.
- See this term in the originalClaude Code Docs — Glossary Anthropic · checked 2026-10-19
- Anthropic — Claude Code docs: Settings files and precedence — Settings precedence(opens in a new window)
- Anthropic — Claude Code docs: Settings files and precedence — Lists merge instead of overriding(opens in a new window)
- Anthropic — Claude Code docs: Settings files and precedence — Settings files and who they affect(opens in a new window)
- Anthropic — Settings — Where settings live(opens in a new window)