Claude Code settings.json: file locations and precedence

The four files, and who each one reaches

Anthropic describes settings as the JSON keys that change how Claude Code behaves: the model it starts on, what it may run without asking, which files it cannot read, how it looks in the terminal, and what an organization enforces. Four files hold them, and each has a scope, meaning the set of people and projects a key saved there applies to.

A bare .claude is the folder inside your project; ~/.claude is the one in your home directory. Installing Claude Code does not create any settings file. The user file appears the first time you change an option in the /config menu that it stores there, such as the theme, and the local file appears the first time you answer “Yes, and don’t ask again” on a permission prompt.

On Windows, ~/.claude means %USERPROFILE%\.claude. If you want the home-directory files somewhere else, set CLAUDE_CONFIG_DIR, and Claude Code keeps settings, session history and plugins there instead.

A managed file is not something you create. It goes in a system directory, and the location depends on the operating system:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux and WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

Two details from Anthropic’s managed settings page matter when you are looking for the file. A managed-settings.d/ directory beside it can hold extra policy files, which Claude Code merges after managed-settings.json in alphabetical order. And Claude Code does not read the legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json, so a policy sitting there is not in force.

Which file wins

When a key appears in more than one place, Claude Code uses the value from the highest level that sets it. The order runs from strongest to weakest:

1. Managed settings. What your organization deploys, whether as a managed-settings.json file, an MDM policy or server-managed settings. Nothing in your own files overrides a managed key, and a flag such as --model chooses only from the models your organization allows. A managed model is a starting default rather than a lock; the locks are availableModels and deniedModels.
2. Command line. JSON passed with --settings <file-or-json> when you start claude, for that session only. It can set any key your user file can set, and it cannot set a Managed or Global config key.
3. Project local settings (.claude/settings.local.json).
4. Shared project settings (.claude/settings.json).
5. User settings (~/.claude/settings.json).

Environment variables are not a level in that stack. Where a behavior has both a shell variable and a settings key, Claude Code decides per pair. ANTHROPIC_MODEL exported in your shell beats the model key from any file, while ANTHROPIC_DEFAULT_MODEL applies only when no file sets model. An env block inside a settings file is an ordinary key, so it follows the five levels above.

Lists combine rather than replace. Set permissions.allow in two files and Claude Code merges both lists, so each file can add entries without removing the other’s. Four keys that hold model lists follow their own rules:

• fallbackModel is an ordered chain, so the whole value comes from the highest file that defines it.
• modelPicker is read only from managed settings, --settings or user settings, and is ignored in project and local files. It needs Claude Code 2.1.242 or later.
• availableModels is applied as-is when a managed source defines it, and non-managed scopes merge their arrays as usual.
• modelSettings resolves one model at a time, together with effortLevel.

A worked example: turning the spinner tips off

While Claude works, Claude Code shows a one-line tip under the spinner. Suppose you set spinnerTipsEnabled to false in ~/.claude/settings.json and the tips come back anyway. One of four things is happening.

Your team’s .claude/settings.json sets it to true. Shared project sits above user, so you see tips in that project and nowhere else. Add "spinnerTipsEnabled": false to .claude/settings.local.json there and your sessions stop showing them without changing anything for your teammates. If your organization’s managed settings set it to true, nothing you write turns the tips off, and neither does --settings. Run /status to see which managed source applies. And if you started the session with claude --settings '{"spinnerTipsEnabled": true}', the command line sits above every file except managed, so that one session shows tips and the next one uses your file again. A flag or an environment variable that pairs with the key can override it as well, regardless of which file set it, so check those before you edit a file again.

settings.json and ~/.claude.json are different files

Claude Code also keeps a fifth file, ~/.claude.json, and it writes that one for itself. You do not need to edit it. It holds your account details, MCP server configurations, per-project state such as trust decisions, and the global config keys that /config writes for you.

A key added to the wrong one of the two files does not apply, so a rule that seems ignored can be sitting in the other file. Anthropic’s debugging page states the split directly: permissions, hooks and env belong in ~/.claude/settings.json, and a rule added to ~/.claude.json is app state that nothing reads as a permission rule. If a permission or hook set at the user level appears to be ignored, check which of the two files it is in before looking for a precedence problem.

The /config menu writes to all three destinations depending on the option. Most options go to ~/.claude/settings.json, a few such as Show tips go to .claude/settings.local.json, and the global config options go to ~/.claude.json. The menu also is not a view of your file: Anthropic notes that the Config tab is not a rendering of your settings.json contents.

Where settings.local.json sits in a git repository

The local file is the one whose location surprises people, because since Claude Code 2.1.211 it does not necessarily live next to the directory you started in. When you answer a permission prompt with “Yes, and don’t ask again” inside a git repository, the approval is saved to .claude/settings.local.json at the repository root and applies across the whole repository, even if you started Claude Code in a subdirectory. In a worktree, Claude Code uses the file at the main checkout’s root.

Four conditions put the file back beside .claude/settings.json instead: outside a git repository, when the repository root is your home directory, on Windows, and when the repository root or its .git or .claude entry is not owned by your user. Paths inside the file do not anchor at the repository root either. A permission rule that starts with / or a relative sandbox path anchors at the session’s primary working directory.

Before 2.1.211, Claude Code kept the file in the starting directory. It still reads a file an earlier version left there alongside the root file. Where both set the same key, the root’s value applies, and permission rules from both files apply.

The shared .claude/settings.json is read from the session’s primary working directory, so a file committed at the repository root applies when you start Claude Code there. After you move a session with /cd, Claude Code reads both project files from the new directory, which needs 2.1.246 or later.

Your local file stays out of your commits without you doing anything, with one exception. The first time Claude Code writes it in a repository that does not already ignore it, it adds **/.claude/settings.local.json to your global git excludes file. That file is core.excludesFile when your global git config sets it to an absolute or ~-prefixed path, otherwise $XDG_CONFIG_HOME/git/ignore, or ~/.config/git/ignore when XDG_CONFIG_HOME is unset. If you created the file by hand and Claude Code has not written to it yet, add it to .gitignore yourself.

Why a rule you wrote is being ignored

Anthropic groups the causes under four headings, and they are worth reading in order.

1. A higher level sets the same key. Another settings file, a --settings flag or a managed source sets it above yours. A flag or environment variable can also override the key on its own, decided key by key.
2. A security key keeps its strict value. For a few keys Claude Code honors the restrictive value from any file, even when a managed source sets the looser one.
3. The file cannot set that value. permissions.defaultMode values auto and bypassPermissions do not take effect from project or local settings and have to be set in user or managed settings, or passed as --permission-mode for one session. Before 2.1.257, bypassPermissions took effect from any file.
4. The file is broken. Invalid JSON or a rejected value makes Claude Code skip the file or the entry.

The strict-value keys are the exceptions to managed precedence. Eleven of them, as Anthropic lists them, honor a restrictive value from a scope that otherwise could not override managed settings:

A committed key that never reaches a teammate

Two things stop a key in .claude/settings.json from applying for everyone who clones the repository. The first is the key’s own scope. Anthropic’s settings index marks a restricted key with one of five values in its Scope column: User, local, or managed, User or managed, User, Managed, or Global config. A key with any of those never applies from the shared file, apart from a few that a repository file can still switch off, and a Global config key applies only from ~/.claude.json. The same restriction inside the env key covers the telemetry export variables.

The second is trust. permissions.allow rules, permissions.additionalDirectories, extraKnownMarketplaces and most env values apply only after each teammate trusts the folder. Until then they still see prompts and do not get plugins from a marketplace the file declares. deny and ask rules apply right away. Your own local file is different: while it stays untracked, its allow rules apply without the trust step, because the file is yours rather than the repository’s.

Permission rules that combine in a way you did not expect

Two documented cases are worth knowing before you read the reports below, because each changes what a rule does. Choosing “Yes, and don’t ask again” saves an allow rule to your local file, and a local allow rule does not outrank an ask rule from a project or managed file, so you can approve a command and still be prompted for it. An organization’s own allow rules also keep applying alongside yours, because permissions.allow merges across scopes unless your organization sets allowManagedPermissionRulesOnly. Neither case accounts for a rule that is ignored outright, which is what three of those reports describe.

Prove which files a session loaded

Anthropic gives one command for the file list and several for the details. Use them in this order.

• /status opens the status dialog, and its Setting sources line lists each settings file Claude Code loaded for the session, such as User settings or Project local settings. A managed entry shows in parentheses how it reached the machine. The line confirms which files were read; it does not say which file supplied each key.
• claude doctor runs from your terminal, prints read-only installation and settings diagnostics without starting a session, and lists entries Claude Code rejected.
• /doctor runs inside a session, checks installation health, invalid settings files, duplicate subagent names and checked-in CLAUDE.md content, and proposes fixes before applying them.
• /permissions shows the resolved allow and deny rules currently in effect, which is the fastest way to see whether your rule survived the merge.
• /hooks lists the hooks registered for the session, grouped by event, and labels each with where it came from.
• /memory shows memory file locations across user and project scopes, and /context breaks down everything in the window, with the source each custom subagent loaded from.
• /debug turns on debug logging for the session and prompts Claude to diagnose using the log and the settings paths.

Claude Code reports a broken file in one of four ways, and which one you get tells you how much of the file is affected. A Settings Error means a user, project or local file has invalid JSON or a value the schema rejects, and the dialog offers to fix the file, exit, or continue without it. A Settings Warning means individual entries failed, such as a malformed permission rule or an unknown hook event name; Claude Code skips those and keeps the rest. Managed settings keep enforcing the rest of the file. A Configuration error means ~/.claude.json could not be parsed. Claude Code copies the broken file to ~/.claude/backups/.claude.json.corrupted.<timestamp> before asking whether to exit and fix it by hand or reset to the default configuration, and to recover your previous state you copy back one of the five most recent .claude.json.backup.<timestamp> files in ~/.claude/backups/, which it saves before it writes the file.

A -p run shows no dialog. Unless a managed settings document cannot be parsed, it skips the broken file or values and continues, so a setting that silently did nothing in a script is a claude doctor question rather than a precedence one.

Safe mode narrows the cause, and clean config removes it

claude --safe-mode turns off CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, custom output styles and custom keybindings. Authentication, model selection, built-in tools and permissions work normally, and managed settings and managed hooks still apply. That boundary is the point: safe mode can rule out a hook or a skill, and it cannot rule out a permission rule, the model, or anything your organization enforces.

For a settings-free test, Anthropic gives the exact recipe. Create an empty directory, change into it, point CLAUDE_CONFIG_DIR at a fresh folder in place of ~/.claude, and start with --setting-sources user:

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

If the problem disappears there, it lives in your user or project configuration; copy files back one at a time to find which. If it persists, the cause is outside them, so check /status for managed settings and your shell for environment variables.

Claude Code on the web reads a different set

A session running on Claude Code on the web runs on a fresh clone in a cloud environment rather than on your machine, and that changes which files reach it. Your user file and your local file are not read at all, and a managed-settings.json file or MDM profile on your device does not travel with the run.

• A thread inside a project: none of a repository’s .claude/settings.json permission rules, hooks or env apply, however many repositories the project has.
• A session with one repository outside a project’s threads: the shared project file is read, because it is part of the clone and the session starts inside it. Commit a key there to have it apply.
• A session with several repositories: in an Anthropic-hosted environment Claude Code reads only the enabledPlugins and extraKnownMarketplaces keys from each repository’s file, not permission rules, hooks, env or other keys. The plugins and marketplaces those two keys declare still do not load in a web run.
• Managed settings: server-managed settings from the claude.ai admin console do reach a web run, and a self-hosted environment also reads the managed settings file in its runner image.
• /config: at claude.ai/code it opens the Claude Code section of your claude.ai settings rather than changing a value. To change a setting for a web run, set an environment variable on the environment.

What people report

The issue tracker carries the location question and the precedence question as separate, long-running threads. The reports below are their authors’ own descriptions, dated and linked so you can read their current state.

• Issue 1202, titled “Documentation error: settings.json location”, opened 2025-05-20 and closed 2025-12-05. At the time of writing it carries 39 reactions and 18 comments. Its reporter found that the file the documentation named did not exist on their machine, and could reach settings only through claude config list.
• Issue 13340, opened 2025-12-07 and still open, 51 reactions, 26 comments: global and local settings.json allow permissions are not respected.
• Issue 18160, opened 2026-01-14 and still open, 50 reactions, 27 comments: Claude is ignoring allow permissions in the global settings.json.
• Issue 18950, opened 2026-01-18 and still open, 72 reactions, 29 comments: skills and subagents do not inherit user-level permissions from settings.json.
• Issue 12962, opened 2025-12-03 and still open, 71 reactions, 22 comments: a request for settings-file traversal into parent directories, for monorepos.

Three of the four open reports describe an allow rule that looks correctly placed and still does nothing. Issues 13340 and 18160 report one in a global or local file that Claude Code does not honour, and 18950 reports a subagent that starts without its parent’s rules. The fourth, 12962, asks for something else: a settings file in a parent directory being read, so a monorepo can keep one policy at its root. The documented behavior above covers the same ground from the other side, and the checks in the previous section are how you tell a merge result apart from a bug in your own file.

Where Omniscio fits

Omniscio starts Claude Code sessions, so it touches settings files in a handful of places, none of which is a general settings editor.

• Hooks it composes. An in-development Hooks panel, hidden until you switch it on in Settings → Lab, manages the Claude Code hooks Omniscio composes into each session it starts and keeps them in Omniscio’s own database rather than writing them into your global ~/.claude config. The hooks it composes for each session reach that session through the one session-private --settings file Omniscio injects when it starts one.
• Attribution, on by default. While Default Agent Instructions is on, every ordinary session it starts merges attribution.commit and attribution.pr into that project’s .claude/settings.local.json, because the Remove AI attribution preset is on by default. Switching that preset off removes the keys the next time a session starts in that project. Omniscio does not write the repository’s tracked .claude/settings.json in that path.
• The cursor worktree, no switch needed. When a cursor-engine session opens a repository that declares .claude hooks, Omniscio isolates it in a worktree and empties that worktree’s own .claude/settings.json and .claude/settings.local.json, so cursor-agent reads no hooks. A repository that declares none runs in place and is left alone.
• Developer guardrails, opt-in. When you turn on developer guardrails in Settings → Features, Omniscio injects one PreToolUse entry into your global ~/.claude/settings.json so every session on the machine is guarded, including ones Omniscio did not start. It is off until you turn it on, and switching it off removes the entry.
• Guard pre-screen, opt-in and narrower. The switch called Speed up agent commands in Settings → Performance skips a slow per-command check for commands that cannot trigger it, and it does that by rewrapping one PreToolUse hook with the Bash|PowerShell matcher in your global ~/.claude/settings.json. On a machine without that heavy guard hook it does nothing, and switching it off puts the entry back.

Two of those writes happen without you turning anything on, so the honest version is not that your settings stay untouched. While Default Agent Instructions is on, every ordinary session it starts merges attribution.commit and attribution.pr into that project’s .claude/settings.local.json, which means a file you never created can appear in a project you open here. That is deliberate: it keeps AI attribution out of commits and pull requests, and switching the Remove AI attribution preset off removes the keys the next time a session starts in that project. The rest of the list is narrower: the hooks it composes for each session reach that session through its own session-private --settings file, and the last two switches write to your global file only once you turn them on.

If you go looking for a rule that vanished, the file to check is the one the list names for that feature. Running several Claude Code sessions at once makes the separation easy to check: open /status in any of them and its Setting sources line names the files that session loaded.