Understanding the settings.json Hierarchy

Claude Code reads its configuration from several files, not one. Each file sits at a different level, and when two files set the same key, the higher level wins. Knowing the order saves you a lot of confusion.

The order, high to low

From the setting that always wins down to the one that gives way first:

1. Managed/enterprise settings (set by your organization)
2. Command line flags you pass when you start Claude
3. .claude/settings.local.json — your personal, per-project file (not committed)
4. .claude/settings.json — the project file, checked into git and shared
5. ~/.claude/settings.json — your user file, applies to every project

So a value in your project file beats the same value in your user file. A flag you pass on the command line beats both. And anything your company manages beats everything.

Why this matters

Say your user file pins one model but the project file pins another. The project wins when you work in that repo. Set a broad default once in your user file, then let each project narrow it.

{
  "model": "sonnet",
  "includeCoAuthoredBy": false
}

That block in ~/.claude/settings.json becomes your baseline everywhere. A project can override either key in its own .claude/settings.json.

The keys you can set

The main keys are model, permissions, env, hooks, includeCoAuthoredBy, cleanupPeriodDays, and apiKeyHelper. The rest of this series covers each one. Once you picture the layers, you always know where to put a setting: user file for your personal defaults, project file for team rules, local file for private tweaks.