Skip to content
Home › Claude Code Configuration & Workflows

Config Hierarchy

Claude Code Configuration & Workflows

Definition

The layered resolution order Claude Code uses to merge settings.json files from multiple scopes into one effective configuration, with higher-precedence scopes overriding conflicting keys from lower ones.

Key points

  • Precedence high→low: Managed > CLI > Local > Project > User. Managed = MDM/enterprise policy (uneditable, cannot be overridden); CLI = command-line flags; Local = .claude/settings.local.json (gitignored, personal); Project = .claude/settings.json (committed, shared); User = ~/.claude/settings.json (all your projects).
  • Distinct from the global ~/.claude.json file, which holds OAuth credentials, MCP registrations, and folder trust — not the same as User settings.json.
  • Common keys: permissions{allow,deny,ask}, hooks, model, env, cleanupPeriodDays (default 30), agent, autoMemoryEnabled, autoMemoryDirectory, claudeMd, claudeMdExcludes, effortLevel, outputStyle, sandbox.enabled, forceLoginMethod, viewMode, disableAllHooks.
  • Settings are merged, not wholesale-replaced: permission rules merge across all scopes rather than the top scope winning entirely.
  • Hot-reload vs restart: permissions, hooks, and credentials hot-reload mid-session; changing model or outputStyle requires a restart.

Why it matters for the exam

  • D3 is 20% of scored content and the precedence chain is a favourite recall question — memorise Managed > CLI > Local > Project > User exactly (order and direction).
  • Expect "which file wins?" scenarios (e.g. a project rule vs a local override, or an enterprise policy that a user cannot override).

Common gotchas

  • Managed settings sit above CLI flags — a policy can block even a flag you pass.
  • ~/.claude.json (global OAuth/MCP/trust) is not User settings.json; don't conflate them.
  • Rules merge, so a deny in a lower scope still applies even if a higher scope has allow — see Permissions Merge And Deny Beats Allow.

See also

Sources

Referenced by