handbookssettings.json
Claude Code reads settings from four files. When two of them set the same thing, one has to win. Here is the order, and the one exception.
- There are four settings files, plus flags you type on the command line.
- Your personal project file beats the team file. The team file beats your global one.
- Your company's managed file beats everything and cannot be overridden.
- Most settings replace each other. Permission lists add together instead.
The four files
You will likely only ever use two of them.
~/.claude/settings.json: yours, applies to every project. Put your model choice and personal preferences here..claude/settings.json: your team's, committed to git. Put shared permissions, hooks, and MCP servers here..claude/settings.local.json: yours, this project only. Claude Code adds it to.gitignorefor you automatically.- The managed file: your company sets this, at an OS-specific path. You cannot override it.
One more file is not in this list: ~/.claude.json holds a small set of global config keys and your personal MCP servers. It follows different rules and is not merged the way the four settings files are.
The smallest working example
Give yourself a sane default model and a hard deny on your secrets.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"model": "claude-sonnet-5",
"permissions": {
"deny": ["Read(./.env)"]
}
}modelpicks your default model for every project, unless a project's own file overrides it.permissions.denyis an array of tool rules.Read(./.env)blocks Claude from reading that specific file, in any project.- The
$schemaline gives your editor autocomplete against the real settings schema. It has no effect on behavior.
Start Claude Code and run /permissions. Your deny rule appears even in a brand-new project with no settings of its own.
The order, strongest first
- Managed: your company's file. Nothing beats it.
- Command-line flags: what you typed when you started Claude.
- Local:
.claude/settings.local.json - Project:
.claude/settings.json - User:
~/.claude/settings.json
Bar width is just a visual cue for strength. A deny rule breaks this order entirely: see the callout below.
Two kinds of settings behave differently
A plain value, a single setting like model, follows this order strictly. The strongest file wins, and the others are ignored entirely.
A list, a setting that holds an array, behaves differently. Claude Code collects the entries from every file that sets it and uses all of them together, rather than letting the strongest file replace the rest. Six settings work this way: permissions.allow, permissions.deny, permissions.ask, permissions.additionalDirectories, sandbox.filesystem.allowWrite, and allowedHttpHookUrls.
Permission lists have one more rule that ignores file order completely. deny beats ask, and ask beats allow. If any file denies something, it stays denied, even if a stronger file explicitly allows it. This is deliberate. A deny is a safety rule, so no weaker or stronger file can quietly switch it off.
When not to use it
Use settings.json for configuration: permissions, your model, hooks, MCP servers. It is not the place for facts and conventions Claude should keep in mind. That is what CLAUDE.md is for. And it is not the place for a reusable multi-step procedure. That is a skill.
More settings worth knowing▾
hooks: lifecycle automation. See Hooks.outputStyle: the active Output Style for the session.cleanupPeriodDays: how long session transcripts are kept. Setting it to0disables session persistence entirely.includeCoAuthoredBy: toggles the "Co-authored-by Claude" trailer on commits Claude creates.disableAllHooks: a kill switch for every hook, regardless of where it is defined.sandbox.filesystem.allowWrite: filesystem sandbox rules, merged like the permission arrays above.autoUpdatesChannel:"latest"or"stable". Stable trails latest by roughly a week.strictPluginOnlyCustomization: a managed-only policy that locks out file-based skills, commands, and agents so only plugins can add customization. Used by organizations that want a single audited distribution channel.
There are well over a hundred documented settings in total. This page covers the dozen that change behavior for most people. The rest are in Anthropic's own settings reference.