ailiteracynepal 🇳🇵
Text size

Chapter 02 · Section I · 12 min read

2.1 Settings files: hierarchy, permissions.json, env

Where Claude Code reads settings from, in what order, and what belongs in each layer. Learn the hierarchy and you stop fighting your own config.

Claude Code layers configuration from several places. Any given setting comes from the most specific layer that mentions it. Understanding the hierarchy is what lets you put team defaults in the repo and personal overrides on your machine without one silently killing the other.

The hierarchy

From lowest to highest precedence:

  1. Built-in defaults. What ships with the CLI.
  2. User settings — ~/.claude/settings.json. Applies to every project on your machine.
  3. Project settings — <repo>/.claude/settings.json. Applies to this repo; committed with it.
  4. Project local settings — <repo>/.claude/settings.local.json. Applies to this repo, gitignored, for your personal overrides.
  5. Environment variables + CLI flags. Highest — override everything for this invocation.

Higher layers override lower ones key-by-key. Arrays (like permissions.allow) are merged, not replaced — so a project can extend the user allowlist without repeating it.

What lives in each layer

LayerGood use
~/.claude/settings.jsonModel preference, personal theme, generally-useful slash-command paths
<repo>/.claude/settings.jsonTeam defaults: permissions.allow, hooks, project skills paths
<repo>/.claude/settings.local.jsonPersonal overrides for this repo — API endpoint, temporarily loosened permissions
Env / flagsOne-off overrides: --permission-mode plan for a single session

Commit the project settings; do not commit settings.local.json. Standard .gitignore entry:

.claude/settings.local.json

Anatomy of settings.json

The main sections you will actually touch:

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Grep", "Bash(npm run test:*)"],
    "deny": ["Bash(rm -rf /*)"]
  },
  "hooks": { /* section 3.3 */ },
  "additionalDirectories": ["/Users/you/shared"],
  "env": {
    "MY_INTERNAL_API": "https://internal.example.com"
  }
}

env deserves calling out: keys defined here are exported to any Bash tool call Claude runs. Handy for passing an internal endpoint or a feature flag without editing shell profiles.

Debugging which layer won

claude config get permissions.allow --explain

The --explain variant tells you which file the value came from. When two layers disagree and you cannot tell why, this is the fastest way to find out.

Check your understanding

Quick check

—

You set `model: claude-sonnet-4-6` in `~/.claude/settings.json` and `model: claude-opus-4-7` in `<repo>/.claude/settings.json`. You launch with no flags in that repo. Which model runs?