Claude Code settings.json: Scopes and Precedence Explained

If you are asking which Claude Code settings file wins, the short answer is: managed settings first, then the --settings flag, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List keys such as permissions.allow are the exception, because they merge across files. This article shows where each file lives, how to set up a shared team file with personal overrides, and how to debug a setting that does nothing.

Everything here comes from the public Claude Code settings documentation. Version numbers quoted below are from that page; check your own version if a behaviour differs.

What are the Claude Code settings files?

Settings are JSON keys that control which model Claude Code starts with, what it may run without asking, which files it cannot read, and what your organization enforces. Claude Code reads four sources, and each has a scope: who the setting applies to.

Installing Claude Code does not create any of these. Claude Code writes ~/.claude/settings.json the first time you change a /config option that it stores in user settings, such as the theme, and .claude/settings.local.json the first time you give a standing approval on a permission prompt, such as "Yes, and don't ask again". There is also ~/.claude.json, which Claude Code writes for itself (account details, MCP server configuration, trust decisions). You do not need to edit it.

On Windows, ~/.claude means %USERPROFILE%\.claude. Set CLAUDE_CONFIG_DIR to keep the home-directory files somewhere else.

Which setting wins when a key appears twice?

Claude Code uses the value from the highest level that sets the key. From highest to lowest:

1. Managed settings. Nothing in your own files or --settings overrides a managed key.
2. Command line: JSON passed with --settings <file-or-json>, for that session only.
3. Project local: .claude/settings.local.json.
4. Shared project: .claude/settings.json.
5. User: ~/.claude/settings.json.

Environment variables are not a level in this stack. Whether a shell variable or a file wins is decided per pair. For example, ANTHROPIC_MODEL exported in your shell applies over the model key from any file, while ANTHROPIC_DEFAULT_MODEL applies only when no file sets model.

Do lists override or merge?

They merge. If permissions.allow appears in your user file and the project file, Claude Code combines both lists, so each file can add entries without removing another's. A few model-related keys follow their own rules. fallbackModel is taken whole from the highest file that defines it, because order carries meaning, and modelPicker is never merged across sources (it also needs v2.1.242 or later).

This matters for permissions: an organization's allow rules still apply alongside yours unless it sets allowManagedPermissionRulesOnly.

How do I set up a team file with personal overrides?

Commit .claude/settings.json so everyone who clones the repository gets the same permissions, hooks and plugins. Each person overrides what they need in their own .claude/settings.local.json.

A small shared file, assembled from rules in the documentation's examples:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

The $schema line gives autocomplete and validation in editors that support JSON schema. The documentation notes the schema can lag behind the newest CLI releases, so a warning on a recently documented key does not always mean your config is invalid.

Settings files are strict JSON. A // comment or a trailing comma is a syntax error, and Claude Code reports a Settings Error at the next start.

One caution from the example file: rules match the command as written. Bash(git push *) does not match git -C . push, and Read(./.env) alone does not stop a grep -r run over the directory. The documentation's team example adds a sandbox block to close that gap, because the sandbox adds your Read deny paths to what sandboxed commands cannot read.

Personal override example

If the team file sets a model and you prefer another, put your choice in the local file:

{
  "model": "claude-opus-5-5"
}

Project local sits above shared project, so only your sessions change. Claude Code adds **/.claude/settings.local.json to your global git excludes the first time it writes the file. If you create the file by hand, add it to .gitignore yourself.

Two details about where the local file lives. When you start Claude Code in a subdirectory of a git repository, it reads and writes the local file at the repository root (from v2.1.211; earlier versions kept it in the starting directory). In a worktree it uses the file at the main checkout's root. And Claude Code reads the shared file from the session's primary working directory, so start it at the repository root to pick up the committed file.

How do I change a setting for one session only?

Three ways, none of which write to a file:

# pass any key a user settings file can set, inline or as a path
claude --settings '{"model": "claude-opus-5-5"}'

You can also use a flag for that key, such as --model or --effort, or export the paired environment variable. --settings sits above user, project and local files but below managed settings, and it cannot set managed or global-config keys.

Commands inside a session mostly save your choice. Changing a value in /config writes to your settings files, and /model saves the model as your default for new sessions. Pressing s in the /model picker switches the model without saving it. Each model has its own prompt cache, so the first request after a switch re-reads the whole conversation uncached.

Claude Code watches the files and applies most edits, including permissions and hooks, to a running session without a restart. Some keys, model among them, are read only at session start; use /model or /effort to change those mid-session.

Why is my setting being ignored?

Start with /status. Its Setting sources line lists each file loaded for the session. It does not tell you which file supplied each key. Run claude doctor to list entries Claude Code rejected. Then check these causes:

• A higher level sets the same key. A managed source, a --settings flag or the local file may override yours. A flag or environment variable can also override a key on its own.
• The value is not allowed in that file. permissions.defaultMode values auto and bypassPermissions do not take effect from project or local settings. Set them in user or managed settings, or pass --permission-mode for one session. Telemetry export variables in an env block also do not apply from project or local files, apart from a few off values.
• The folder is not trusted yet. permissions.allow rules, permissions.additionalDirectories, extraKnownMarketplaces and most env values from the committed file wait until each teammate trusts the folder. deny and ask rules apply immediately. Allow rules in an untracked local file do not wait for trust.
• The file is broken. Invalid JSON gives a Settings Error dialog in an interactive session. A bad single entry, such as a malformed permission rule, gives a Settings Warning and Claude Code skips just that entry. In a -p run there is no dialog, so Claude Code skips the broken file or values without asking; run claude doctor afterwards.
• A "don't ask again" rule still prompts. That choice saved an allow rule to your local file, and an allow rule there does not outrank an ask rule from a project or managed file.

A few restrictive keys are honored from any scope even when managed settings say otherwise, for example disableClaudeAiConnectors: true and permissions.blockReadsOutsideWorkingDirectories: true (the latter needs v2.1.257 or later). So a project setting can make a session stricter than policy, never looser.

Do settings apply in cloud sessions?

Only partly. A cloud session runs on a fresh clone, so it reads the committed .claude/settings.json (for a single-repository session outside a project's threads) but not your user file or your local file. A managed-settings.json on your device does not reach it; server-managed settings do. Skills, plugins and CLAUDE.md follow their own rules, listed in the cloud environment docs.

A sensible layout

• User file: theme, editor mode, a default model, personal allow rules.
• Shared project file: team allow and deny rules, hooks, the plugins and marketplaces the project needs.
• Local file: experiments before you share them, and personal exceptions.
• Instructions that are prose, not config, belong in a CLAUDE.md file rather than in settings.

This article covers Claude Code itself. Atlas is an independent team of AI engineers built on Claude Code; it runs each engineer as its own Claude Code session.

Conclusion

Put each setting in the narrowest file that matches who it should affect: user for you everywhere, shared project for the team, local for you in one repo, managed for policy. Remember that lists merge, scalars follow the precedence stack, and some keys are refused in project files by design. When anything behaves oddly, /status and claude doctor are the first two things to run.