Which Claude Code settings.json wins? File locations and precedence

Claude Code reads ~/.claude/settings.json, the project's .claude/settings.json and .claude/settings.local.json, plus managed settings. For a single key, the highest level wins: managed, then --settings on the command line, then settings.local.json, then the project file, then your user file. Lists like permissions.allow merge across every file.

The settings files

FileScopeTypical contents
~/.claude/settings.jsonYou, every projectDefault model, theme, your own permission rules
.claude/settings.jsonEveryone in the repo once committedTeam permissions, hooks, plugins, env vars
.claude/settings.local.jsonYou, this projectPersonal overrides and the rules saved by "Yes, and don't ask again"
managed-settings.json (or MDM / admin console)Your organizationSecurity policy you can't override

Precedence, highest first

  1. Managed settings. Nothing below can override a managed key.
  2. Command line. claude --settings '{...}' for that one session.
  3. Project local: .claude/settings.local.json.
  4. Shared project: .claude/settings.json.
  5. User: ~/.claude/settings.json.

Example: your user file sets "model" to one model and the team's project file sets another. Inside that repo the project value wins. To get yours back only for yourself, put the same key in .claude/settings.local.json; your teammates don't see the change.

Lists merge, they don't override

Precedence applies to single values. Arrays such as permissions.allow and permissions.deny are combined from every file. So this user file and this project file produce three allow rules, not one:

// ~/.claude/settings.json
{ "permissions": { "allow": ["Bash(git status)"] } }

// .claude/settings.json
{ "permissions": { "allow": ["Bash(npm run *)", "Bash(npm test)"] } }

For permissions, deny is checked first, then ask, then allow, across all files together. A deny in your user file blocks a tool that the project allows, and the reverse is also true.

When a setting seems ignored

  • A higher file sets the same key. Run /status to see which sources loaded.
  • The JSON is broken. A trailing comma or a rejected value makes Claude Code skip the file or the entry.
  • The project folder isn't trusted yet. Allow rules and most env values in a committed .claude/settings.json wait until each person trusts the folder. Deny and ask rules apply right away.
  • Some keys only work from user or managed settings. For example, permissions.defaultMode values auto and bypassPermissions don't take effect from project files.
  • You started Claude in a subfolder. The shared .claude/settings.json is read from the session's working directory, so start Claude at the repo root to pick up a root file.

Instructions follow different rules: CLAUDE.md files all stack into context instead of overriding. See where Claude Code looks for CLAUDE.md. For the permission rules themselves, read how to stop Claude Code asking permission.

Questions

Where is Claude Code's settings.json on a Mac?
Your personal file is ~/.claude/settings.json. Each project can add .claude/settings.json (shared, committed) and .claude/settings.local.json (yours, kept out of git). Installing Claude Code creates none of them; they appear when you or Claude Code first write a setting.
Does settings.local.json override settings.json?
Yes. For the same key, .claude/settings.local.json beats the project's .claude/settings.json, which beats ~/.claude/settings.json. Managed settings and --settings on the command line sit above all three.
Why does a permission rule from another file still apply?
List keys such as permissions.allow merge across files instead of replacing each other, so every file's entries count. And a deny rule from any file blocks the tool even if another file allows it.
What is ~/.claude.json?
A separate file Claude Code writes for itself, with account details, MCP server configurations and per-project state such as trust decisions. Your preferences belong in ~/.claude/settings.json instead.
How do I see which settings files loaded?
Run /status in a session. It lists the setting sources in effect, including any managed source from your organization.

Rulebook for Mac

Rulebook is a native Mac app we are building for these files. It shows every CLAUDE.md and settings.json level side by side, lets you drag a rule from one file to another, and edits permissions without hand-written JSON. See the features.

Rulebook is in development and not available yet.

Email us about the launch

Related guides