Claude Code settings.json: Which File, Which Key

Claude Code has no single config file. It has four, and each one decides who a setting applies to. Put a key in the wrong file and it silently does nothing for your teammates.

1. The four files

• ~/.claude/settings.json — user. You, in every project on this machine.
• .claude/settings.json — shared project. Everyone who clones the repo. Commit it.
• .claude/settings.local.json — project local. You, in this one project. Claude Code adds it to your global git excludes the first time it writes the file; if you create it by hand, gitignore it yourself.
• managed-settings.json, MDM, or the claude.ai console — managed. Your organization.

2. Precedence, highest first

Managed → claude --settings → project local → shared project → user. A key set higher wins. List keys are the exception: permissions.allow and friends merge across files rather than replacing each other, so each file can add rules without deleting another’s.

3. The keys worth setting

Settings files are strict JSON — a // comment or a trailing comma is a parse error.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "defaultMode": "ask",
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"],
    "additionalDirectories": ["../shared-lib"]
  },
  "env": { "NODE_ENV": "development" }
}

What it does: pins the starting model, pre-approves your lint and test commands, blocks reads of .env files, grants access to a sibling directory, and exports an env var to every session and its subprocesses.

The $schema line gives you autocomplete and inline validation in VS Code and Cursor. hooks also lives here, but its value is a nested object of matchers — see the hooks guide rather than guessing the shape. defaultMode accepts ask, auto, plan, and bypassPermissions; the last two don’t take effect from project or local files.

4. Confirm what loaded

/status

What it does: shows a Setting sources line listing every settings file this session read. Most edits reload without a restart; model and outputStyle wait for /model or a restart. If a file was rejected, claude doctor says what it dropped.

Next: build a file visually with the settings builder, or read how permissions and allowlists work.