skip to content

A key committed to a repository's .claude/settings.json does nothing in one developer's Claude Code session — how do you find out why?

level: seniorimportance: should knowfreq 11%

answer

  1. evidence before guesses
  2. the Setting sources line
  3. something above the shared file
  4. scope, trust, starting directory
  5. claude doctor for dropped entries

basics

~20 s

Run /status to see which files loaded, then check for a higher layer setting the key, a key the shared file can't set, workspace trust not yet accepted, a broken or unread file, or a startup-only key.

solid answer

~40 s

I start with `/status`, whose `Setting sources` line lists the files the session loaded, and `claude doctor`, which lists rejected entries. Then I walk the causes. A higher level may set the key: the developer's `.claude/settings.local.json`, a `--settings` in a launch alias, managed settings, or a paired flag or environment variable. The key's scope may exclude the project file — `permissions.defaultMode` values `auto` and `bypassPermissions`, global config keys, some `env` variables. Allow rules, `additionalDirectories` and most `env` values wait until the folder is trusted. The file may not have loaded: started from a subdirectory instead of where it is committed, or invalid JSON. Finally, keys like `model` are read only at startup.

code

bash · 8 lines
bash
# Validation errors and rejected entries, without starting a session
claude doctor

# A session that skips CLAUDE.md, skills, plugins, hooks and MCP servers
claude --safe-mode

# A session with none of your ~/.claude files, started outside the project
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

go deeper

for a junior

Remember that /status shows which settings files loaded and that a value in a higher file wins over the committed one.

for a middle

Explain the categories: a higher layer, a key the project scope can't set, workspace trust, a broken file, and keys read only at session start.

for a senior

Diagnose from evidence: Setting sources, claude doctor, the starting directory and launch wrappers, then a clean-configuration comparison, rather than re-editing the file and hoping.

for a principal

Decide which team requirements can live in a committed file that each developer can override or leave untrusted, and which need managed settings to hold reliably.

## Start with what loaded A setting that "does nothing" is usually not a bug: something else decides the value, the file can't set it, it hasn't been allowed to apply yet, or the file never loaded. Diagnose in that order, starting from evidence rather than guesses. 1. Run **`/status`** in the developer's session. The **Status** tab has a `Setting sources` line listing each settings file loaded for this session — `User settings`, `Project local settings` and so on — and, when managed settings apply, how they reached the machine. 2. Run **`claude doctor`** from a terminal. It prints read-only settings diagnostics, including validation errors and entries Claude Code rejected, without starting a session. 3. Compare against the precedence stack for the specific key. `/status` confirms which files were read; it doesn't say which file supplied each key, so the rest is reasoning. ## Cause 1: a higher level sets the same key The stack, highest first, is managed settings, command line (`--settings` and flags), `.claude/settings.local.json`, `.claude/settings.json`, `~/.claude/settings.json`. The committed file loses to: - the developer's own `.claude/settings.local.json` setting the same key; - a `--settings` file or inline JSON in a launch alias or wrapper script; - managed settings, which nothing in the developer's files overrides; - a paired flag or environment variable — for example an exported `ANTHROPIC_MODEL` overrides the `model` key from any file, decided per pair rather than by level. ## Cause 2: the shared file can't set that key Each key's entry in the settings reference has a scope. Keys scoped to user, local or managed, managed-only keys, and **global config** keys (read only from `~/.claude.json`) never apply from the committed file. Specific cases: - `permissions.defaultMode` values `auto` and `bypassPermissions` don't take effect from project or local settings; they belong in the user file, managed settings or `--permission-mode`. - Some variables in the `env` block — those that choose where Claude Code writes its files, such as `CLAUDE_CONFIG_DIR`, and the telemetry exporter variables — are dropped from project and local files. - A few security keys keep their strict value whichever file sets the looser one. ## Cause 3: the key waits for workspace trust `permissions.allow` rules, `permissions.additionalDirectories`, `extraKnownMarketplaces` and most `env` values in a committed file apply only after the developer **trusts the folder**. Until then they still see prompts and get no plugins from the declared marketplace. `deny` and `ask` rules apply immediately. A teammate who dismissed the trust dialog sees "the allow rules don't work". ## Cause 4: the file never loaded, or loaded partly - **Wrong directory.** The shared `.claude/settings.json` is read from the session's **primary working directory**. A developer who starts Claude Code in `packages/api` doesn't get a file committed at the repository root — while the local file, by contrast, is read and written at the repository root. - **Broken JSON.** Settings files are strict JSON; a comment or trailing comma produces a **Settings Error** dialog at interactive start (fix with Claude's help, exit, or continue without the file). - **A bad entry.** A **Settings Warning** skips individual values, such as a malformed permission rule or an unknown hook event, and keeps the rest. - **Non-interactive runs.** A `-p` run shows no dialog and silently skips the broken file or values, so check `claude doctor` afterwards. ## Cause 5: the key is read only at startup Claude Code watches settings files and applies most edits live, including `permissions` and `hooks`. A few keys are read once at session start — `model`, `effortLevel`, `modelSettings` — so editing them mid-session changes nothing until the next session (or use `/model` and `/effort`). ## Summary table | Symptom | Likely cause | Check | | :- | :- | :- | | Value differs from the file | Higher level or paired variable | `/status`, launch flags, shell exports | | Allow rules ignored | Folder not trusted | Accept the trust dialog | | Key ignored only in the repo file | Key's scope excludes project | Settings reference scope | | Whole file missing from sources | Started in a subdirectory, or broken JSON | Start at the root, `claude doctor` | | Edit had no effect until restart | Startup-only key | New session | When none of this explains it, compare against a clean configuration: `claude --safe-mode`, or `CLAUDE_CONFIG_DIR` pointed at an empty directory and a launch from a folder with no `.claude`.

  • The developer launched Claude Code from packages/api inside the repository. Could that explain it?
    Yes. Claude Code reads the shared `.claude/settings.json` from the session's primary working directory, so a file committed at the repository root isn't read when the session starts in a subdirectory. The local file behaves differently: Claude Code reads and writes it at the repository root. Starting at the root fixes it, and `/status` shows the difference.
  • The same key works when the developer puts it in ~/.claude/settings.json but not in the committed file. What does that point to?
    The key's scope. Some keys or values never apply from a repository file: `permissions.defaultMode` set to `auto` or `bypassPermissions`, keys scoped to user or managed settings, global config keys that live only in `~/.claude.json`, and some `env` variables such as `CLAUDE_CONFIG_DIR`. The settings reference lists each key's scope.
  • Why can a non-interactive claude -p run ignore a setting without any visible error?
    A `-p` run shows no Settings Error dialog. Unless managed settings can't be parsed, Claude Code skips the broken file or the rejected values and carries on with the rest. After such a run, `claude doctor` shows what it dropped.

  • If /status lists the project file, every key in it must be in effect
  • Any key that works in the user file also works from the committed file
  • Committed allow rules apply the moment a teammate clones the repository
  • Every settings edit needs a restart before Claude Code notices it
  • A malformed settings file stops Claude Code from starting at all