Which settings file wins when two of them set the same key

Two files set the same key. Which one applies?

Two things surprise people who assume plain overriding: lists are merged, and some keys let a lower level win.

Five levels

Highest first. A key at a higher level overrides the same key below it.

3 sits above 4, which is the useful part. A value your team set in the shared file can be put back for you alone in settings.local.json — without editing the file everyone shares.

Nothing beats managed. Not --settings, and --model picks only from the models your organisation allows.

Lists are merged, not overridden

A list key such as permissions.allow, set in more than one file, is combined rather than resolved to one winner.

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

// .claude/settings.json  (your team's)
"permissions": { "allow": ["Bash(git commit *)"] }

// → both apply

Which also means entries cannot be removed from below. A lower-level file cannot subtract what a higher one added. Use deny, or edit that file.

Four keys that do not merge

The model-related keys have their own rules.

Environment variables are not a level

They are not part of the stack. Which one applies is decided per key.

Two variables that both choose a model: one wins, one yields. Check the pair for the key you care about.

An env block inside a settings file is an ordinary key and follows the five levels above.

Seven keys where a lower level beats managed

For security-sensitive keys, Claude Code honours the more restrictive value.

This works in one direction only. A project true for remoteControlAtStartup is ignored. useAutoModeDuringPlan and syncClaudeAiSkills ignore a false written in the shared .claude/settings.json, while honouring one from local.

enableArtifact cannot be turned back on. Once anything sets it false, nothing — managed included — restores the Artifact tool.

When a setting does not apply

/status        # which files were loaded
claude doctor  # the resolved settings, and any skipped rules

Three causes:

• A higher level sets the same key — see the table above
• That file cannot set that value — permissions.defaultMode values auto and bypassPermissions do not take effect from project or local settings (before v2.1.257, bypassPermissions took effect from any file)
• The key is out of that file's scope entirely — 71 of the 223 keys

The full list for the third one:

https://quintetkit.github.io/en/reference/claude-code-settings-scope.html

Checking it

The "cannot set that value" cases are mechanically detectable.

npx @quintetkit/ccheck

warn  .claude/settings.json:12
      `defaultMode: bypassPermissions` does not take effect from project or local settings.
      why: https://code.claude.com/docs/en/settings-reference

Precedence itself is not checked. Which files load is decided at run time and cannot be known from the files in front of you. What cannot be determined is not judged.

Source

https://code.claude.com/docs/en/settings

Based on a snapshot taken 2026-09-04.