Home / Extending: skills, MCP, subagents, hooks, plugins

settings.json in depth

Five levels of settings.json follow one another from strongest to weakest, a scalar key common to two files is decided by the highest-priority level, but most lists, including permissions.allow and permissions.deny, merge across levels instead of overwriting each other.

A project settings.json overrides the user's on a scalar key that both files define, and five levels follow one another before reaching this result (source code.claude.com/docs/en/settings, accessed on 2026-09-02).

Five levels, only one wins by default

From strongest to weakest: managed settings, set by an MDM or by the claude.ai console; the --settings option passed on the command line, valid for a single session; .claude/settings.local.json, private to the machine, never shared via git; .claude/settings.json, shared via git with the rest of the team on this project; and finally ~/.claude/settings.json, set once for every project opened on this machine. On a simple key present at two levels at once, the higher-ranking one wins entirely, the weaker level is not read. Managed settings stay out of reach of editing from the workstation, set by an organisation, whereas the other four levels are plain text files that anyone can open and edit directly.

Lists merge, except for four keys

The rule changes as soon as a key holds a list. permissions.allow and permissions.deny, among others, merge across levels: an entry set at user level stays active even when the project adds another one alongside it. Four keys escape this merging, each following its own rule rather than a single one. fallbackModel takes the entire value from the highest-priority level that defines it. modelPicker takes the entire value from the highest priority among managed settings, --settings and the user settings, and simply ignores the key if it is only set at project or local level. availableModels, when managed settings define it, applies as is and ignores whatever the user, project or local level add, and does not merge across several managed sources either. modelSettings is resolved model by model, with effortLevel, each entry specifying itself which file applies to which model.

{
  "permissions": {
    "allow": ["Bash(npm test)"],
    "deny": []
  },
  "env": {
    "NODE_ENV": "development"
  }
}

The env block follows the same rule

The env block inserted in a settings file is an ordinary key that follows the same five levels as the rest of the file, but most of its values, like the permissions.allow rules, only take effect once each team member has trusted the project's folder. A shell environment variable is not a level in this stack: when a behaviour has both a variable and a settings key, which of the two applies is decided pair by pair, not by level, ANTHROPIC_MODEL exported in the shell winning, for instance, over the model key in any file, whereas ANTHROPIC_DEFAULT_MODEL only applies if no file sets model.

This hierarchy makes full sense as soon as a hook comes into play: the declaration of an event, like the one described in hook events, from trigger to message, also lives in this same file, and follows exactly the same order of priority between project and personal machine.