Settings and env

The hierarchy

Unlike memory and rules, settings have a real, deterministic precedence order. Higher entries win outright.

graph TD
    A["1. Enterprise managed policy<br/><i>/etc/claude-code/managed-settings.json</i>"] --> B["2. Command-line arguments<br/><i>--model, --permission-mode, ...</i>"]
    B --> C["3. .claude/settings.local.json<br/><i>yours, this project, gitignored</i>"]
    C --> D["4. .claude/settings.json<br/><i>team, committed</i>"]
    D --> E["5. ~/.claude/settings.json<br/><i>yours, all projects</i>"]

Read it as: 1 beats 2 beats 3 beats 4 beats 5. If model is set in both ~/.claude/settings.json and .claude/settings.json, the project file wins.

Resolution is per key, not per file. A user-level file still supplies every key the higher-priority files leave unset, so you do not have to restate your whole configuration to override one value.

Strict JSON

Settings files are parsed as strict JSON. No // comments, no trailing commas, no single quotes. A stray comment produces a Settings Error at startup and the whole file is ignored, which looks exactly like “Claude Code is ignoring my configuration.”

Add the schema line for editor validation:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

What env does

The env block writes key/value pairs into the Claude Code process environment. It is applied at startup and re-applied whenever the settings file changes. Because Claude Code reads it from the file directly, it takes effect regardless of how claude was launched: from a shell, from an IDE, from a launcher that never sourced your .bashrc.

Everything Claude Code spawns inherits these variables:

graph TD
    S["settings.json env block"] --> CC["Claude Code process"]
    CC --> B["Bash tool commands<br/><i>make build, go test, mvn verify</i>"]
    CC --> H["Hook commands"]
    CC --> SL["Status line command"]
    CC --> MCP["stdio MCP servers"]

That inheritance is the point. An IDE-launched session that never read your shell profile still gets the right JAVA_HOME, so mvn verify behaves identically whether Claude ran it or you did.

Tuning Claude Code itself

Variables it reads for its own behaviour:

Setting up the toolchain

The one that matters in a polyglot repo:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "JAVA_HOME": "/usr/lib/jvm/java-21-openjdk",
    "MAVEN_OPTS": "-Xmx2g",
    "GOFLAGS": "-mod=mod",
    "GOPRIVATE": "github.example.internal/*",
    "PYTHONPATH": "./src",
    "NODE_OPTIONS": "--max-old-space-size=4096",
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "API_TIMEOUT_MS": "1200000"
  }
}

Since JSON cannot carry comments, here is the annotation separately:

A useful convention: keep the annotation table in CLAUDE.md rather than in a sibling file nobody opens. It is short, it is genuinely non-obvious, and it stops the next person deleting a variable they do not recognise.

Behavioural rules for env

Permissions

Permissions live in settings but resolve differently from every other key: they merge across scopes, and a deny beats an allow from anywhere.

{
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(go test *)",
      "Bash(git status *)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(gh pr create *)"
    ],
    "deny": [
      "Write(**/generated/**)",
      "Edit(**/generated/**)",
      "Read(./.env)",
      "Read(**/secrets/**)",
      "Bash(git push --force *)",
      "Bash(rm -rf *)"
    ]
  }
}

deny on Read is worth knowing about: it is the mechanism that keeps .env files and credential directories out of the context window entirely, rather than relying on an instruction asking Claude not to look.

Frequently used keys

Splitting committed from local

The division that works in practice:

Add .claude/settings.local.json and CLAUDE.local.md to .gitignore in the same commit that creates .claude/. Doing it later means doing it after someone has already pushed a token.