# Claude Code settings.json: Scopes and Precedence Explained

> Which Claude Code settings file wins? The four scopes, precedence order, list merging, a team setup and fixes for settings that seem ignored.

24 October 2026 · Technical · How-to · 7 min read · https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/

## The short version

- Claude Code reads settings from user, shared project, project local and managed scopes, and the file a key lives in decides who it applies to.
- When a key is set in several places, managed settings win, then the --settings flag, then project local, shared project and user; list keys such as permissions.allow merge instead.
- Commit .claude/settings.json for the team, keep personal overrides in .claude/settings.local.json, and run /status to confirm which files loaded.
- A setting that seems ignored usually has a higher level overriding it, a value that is not allowed in project files, a folder not yet trusted, or a broken JSON file.
- Settings files are strict JSON, so a comment or trailing comma breaks the file; claude doctor lists what Claude Code rejected.

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.

| Scope | File | Applies to |
| :- | :- | :- |
| User | `~/.claude/settings.json` | You, in every project on this machine |
| Shared project | `.claude/settings.json` | Everyone who clones the repo, if you commit it |
| Project local | `.claude/settings.local.json` | You, in this one project |
| Managed | `managed-settings.json`, MDM policy or server-managed settings | Everyone your organization deploys it 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:

```json
{
  "$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:

```json
{
  "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:

```bash
# 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.

## Questions people ask

### Which Claude Code settings file takes precedence?

Managed settings are highest, then the --settings flag, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List keys such as permissions.allow merge across files instead of overriding.

### Should I commit .claude/settings.json?

Yes, if you want teammates to share permissions, hooks and plugins. Personal exceptions go in .claude/settings.local.json. Claude Code keeps that file out of git when it creates it; if you create it by hand, add it to .gitignore.

### How do I check which Claude Code settings loaded?

Run /status and read the Setting sources line, which lists the files loaded. It does not show which file supplied each key. Run claude doctor to see entries Claude Code rejected.

### Why does my allow rule in the project settings not work?

Allow rules in the committed project file apply only after each teammate trusts the folder. A higher level, such as a managed policy, or a broken JSON file can also override or skip it.

### Can I change a Claude Code setting for just one session?

Yes. Pass JSON with --settings, use a key-specific flag such as --model, or export the paired environment variable. None of these write to your settings files.

## About Atlas: One Claude Code session per engineer

Atlas is a team of AI engineers built on Claude Code, and each engineer is its own Claude Code session with a written role and its own working folder. Atlas is an independent product. — https://bridge-terminal.com/atlas/

## Sources

- [Claude Code: Settings files and precedence](https://code.claude.com/docs/en/settings)
- [Claude Code: Example settings files](https://code.claude.com/docs/en/settings-example)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._