Claude Code / configuration field notes
Claude Code settings: scopes, precedence, and what actually loaded
~/.claude/settings.json, shared repository policy in .claude/settings.json, and one-user project overrides in .claude/settings.local.json. Use --settings for a one-session file, and --setting-sources to choose which built-in sources load. Higher-precedence sources override scalar values; list settings merge. Use /status to inspect active sources and claude doctor to catch invalid settings.We ran an isolated Windows setup-hook capture with Claude Code 2.1.283. User, project, local, source-filter, malformed-local, repaired-local, and CLI settings each produced a visible marker. The CLI case was rerun with stdin closed and returned exit code 0. No account, API key, OAuth flow, or model request was used, so model-backed behavior is Untested.
Choose the file by audience
| Scope | File or option | Use it for | Precedence |
|---|---|---|---|
| User | ~/.claude/settings.json | Personal defaults across projects | Lowest file scope |
| Shared project | .claude/settings.json | Repository policy teammates should review | Above user |
| Project local | .claude/settings.local.json | Personal overrides for one checkout; normally not committed | Above shared project |
| One session | claude --settings file.json | A temporary or CI-specific settings payload | Above project local |
| Managed | managed-settings.json or a managed source | Organization policy | Highest |
~/.claude.json is application state. Do not use it as a substitute for the settings files that hold permissions, hooks, or environment configuration.Make precedence observable
# Load the normal three file sources and add one session file
claude --settings session-settings.json \
--setting-sources user,project,local \
--init-only
# Limit a run to one source
claude --setting-sources user --init-onlyThe exact file names make the intended audience reviewable. The command-line file is useful for a disposable experiment or a controlled CI invocation; it should not become a hidden replacement for repository policy.
Settings are JSON, not “JSON-ish”
Keep the files strict JSON. A malformed local file should be treated as an incident to repair, not as a configuration format. In the lab, the malformed local fixture did not erase the valid project marker from the captured environment; that is a local observation, not a promise about every future release or every setting.
Local capture: eight source cases
Each case used disposable user, project, and local files. A Setup command hook appended the resolved marker as JSONL. The test intentionally stopped before model processing, so the evidence is about source resolution only.
| Case | Captured marker | Exit | What it shows |
|---|---|---|---|
| User | user | 0 | User source can supply the value |
| Shared project | project | 0 | Project value overrides the user scalar |
| Project local | local | 0 | Local value overrides both lower file scopes |
CLI --settings | cli | 0 | One-session file wins over loaded file scopes in this capture |
| User-only filter | user | 0 | --setting-sources user excludes project and local values |
| Malformed local JSON | project | 0 | Lower valid project value remained visible |
| Numeric env value | 123 | 0 | Captured process environment exposed it as text |
| Repaired local | repaired | 0 | Corrected local file supplied the replacement |
Download the settings observation CSV Download the scope diagram
/status UI output, authentication, and a model following a setting remain Untested.Debug a surprising setting
- Record the exact command, working directory, and source list.
- Run
/statusin an authenticated session to inspect active setting sources. - Run
claude doctorwhen a file is invalid or a source does not behave as expected. - Temporarily narrow sources with
--setting-sourcesto isolate one layer. - Change one scalar or list at a time, then repeat the same harmless check.
Do not infer “the file exists” from “the value was used.” A file can exist, be skipped, be overridden, or load successfully without a model following its contents.
FAQ
Should settings.local.json be committed?
Usually no. Use it for a personal override in one checkout. Commit the shared project file when the team should review and inherit the policy.
What wins: a CLI settings file or a project file?
Claude Code documents command-line --settings as higher precedence than project settings. The local capture also observed the CLI marker after the retry.
Did this test prove Claude used the setting during a model answer?
No. It proved only that a setup hook captured the resolved marker. No login or model request was available, so model behavior remains untested.
Why is the number test not called invalid?
The hook receives environment values as process text. The capture saw 123; that does not validate the number as a legal value for unrelated Claude Code settings.