# Claude Code settings.json: Which File, Which Key

> The four settings files Claude Code reads, which one wins when they disagree, and the handful of keys worth setting on day one.

- Canonical: https://guides-ai.pages.dev/guides/claude-code-settings-json/
- Plate 03.08 · Topic: Claude Code commands (https://guides-ai.pages.dev/topics/commands/)
- Published: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

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.

```json
{
  "$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

```text
/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](/tools/claude-code-settings/), or
read [how permissions and allowlists work](/guides/claude-code-permissions/).