Claude Code settings.json: every scope, and which file wins

Last updated: November 11, 2026

TL;DR

Claude Code settings live in four JSON files plus whatever your organization manages: ~/.claude/settings.json for you everywhere, .claude/settings.json for everyone in a project, .claude/settings.local.json for you in one project, and managed settings for everyone your organization deploys to. When the same key appears in more than one, the highest level wins: managed, then the command line, then project local, then shared project, then user.

• 📁 Pick the scope first. The file decides who a setting reaches, so choose it before you write the key.
• 🤝 Commit the team file. .claude/settings.json reaches teammates only once it's in the repository.
• 🙋 Override in the local file. .claude/settings.local.json beats the team file for you alone, and Claude Code keeps it out of git when it creates it.
• ➕ Lists add up. permissions.allow and other list keys merge across files instead of replacing each other.
• 🔍 Check with /status. Its Setting sources line lists every file that loaded.

Everything here comes from Anthropic's settings files and precedence page and its managed settings page, read on November 11, 2026, with Claude Code at 2.1.322 on npm.

Before you start

You need Claude Code installed and a project folder. Three things shape how the steps below go:

1. No file exists yet. Installing Claude Code doesn't create any settings file. Claude Code writes ~/.claude/settings.json the first time you change a /config option such as the theme, and .claude/settings.local.json the first time you choose "Yes, and don't ask again" on a permission prompt.
2. Strict JSON. A // comment or a trailing comma is a syntax error, and Claude Code reports the file as a Settings Error at the next start.
3. Your organization may already decide some keys. If it manages Claude Code, nothing in your own files changes a managed key. Step 6 shows how to tell.

Step 1: Pick the file for the setting

Each file has a scope: the people and projects a key saved in it applies to. Pick by who should get the setting, not by where it's easiest to type.

~/.claude is the .claude folder in your home directory, and a bare .claude is the one inside your project. On Windows, ~/.claude means %USERPROFILE%\.claude.

Claude Code also keeps a fifth file, ~/.claude.json. It holds your account details, MCP server configurations and per-project trust decisions, and Anthropic says you don't need to edit it.

Step 2: Write the key

Open the file for your scope and add the key. This example lets Claude Code run your lint and test commands without asking and stops it reading .env files:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

The $schema line points to the published JSON schema, which gives you autocomplete and inline validation in VS Code, Cursor and other editors that read JSON schema. Anthropic notes that the schema can lag the newest releases, so a warning on a recently documented key doesn't mean the file is wrong.

You don't need to restart. Claude Code watches its settings files and applies most edits to the running session, including permissions and hooks. Two common keys wait for a new session: model and effortLevel. Use /model and /effort to change those mid-session.

/config is the other way in. Its Config tab lists a short set of personal options, not every key, and it saves most of them to ~/.claude/settings.json. It's part of the terminal interface, so the VS Code chat panel and the desktop app don't open it.

Step 3: Share the team file

Commit .claude/settings.json so everyone who clones the repository gets the same permissions, hooks and plugins. Until it's committed, it's a file on your disk that nobody else has.

Two things can still keep a committed key from reaching a teammate:

• The key waits for trust. permissions.allow rules, permissions.additionalDirectories, extraKnownMarketplaces and most env values apply only after each person accepts the trust dialog for the folder. deny and ask rules apply right away.
• The key can't be set from a repository. Anthropic's settings index marks some keys as user, local or managed only, and those never apply from the shared file. Two examples: permissions.defaultMode set to auto or bypassPermissions doesn't take effect from a project or local file, and neither do telemetry export variables in an env block, apart from a few off values.

That second point is why a security rule for a team belongs in managed settings rather than the repository. The shared file is a good default for the team, not a lock.

Step 4: Override it for yourself

To change a setting for yourself in one project, put it in .claude/settings.local.json. Project local sits above shared project, so your value wins in your sessions and your teammates' sessions don't change. Anthropic's example: the team file sets "model": "claude-sonnet-5", you put "model": "claude-opus-5-5" in your local file, and only your sessions move to Opus.

Three details about this file are easy to miss:

• Claude Code keeps it out of git, if Claude Code created it. The first time it writes the file, it adds **/.claude/settings.local.json to your global git excludes. If you created the file by hand, add it to .gitignore yourself.
• Its allow rules skip the trust step, as long as the file stays untracked. If git tracks it, the trust step applies to it too.
• In a git repository, it lives at the root. Start Claude Code in a subdirectory and it still reads and writes the local file at the root, so a standing approval covers the whole repository. In a worktree, it uses the main checkout's root. The exceptions include Windows and a repository rooted at your home directory, where the file stays beside .claude/settings.json. This changed in 2.1.211; before that, the file sat in the starting directory.

Step 5: Try a value for one session

To test a value without saving it, set it when you start Claude Code. Your files stay as they were. There are three ways:

• The settings flag. Pass JSON, inline or as a file path, with the settings flag when you launch claude. It sits above your user, project and local files and below managed settings, and it lasts one session.
• A flag for that key. Some keys have their own launch flag, such as the model flag for model.
• An environment variable. Export the key's paired variable first, such as ANTHROPIC_MODEL for model.

Environment variables aren't a level in the stack. Which one wins is decided per pair: ANTHROPIC_MODEL in your shell beats the model key in any file, while ANTHROPIC_DEFAULT_MODEL applies only when no file sets model. An env block inside a settings file is different. It's an ordinary key and follows the normal levels.

Step 6: Confirm what loaded

Run /status and open the Status tab. The Setting sources line lists each file Claude Code loaded for the session, such as User settings or Project local settings. When managed settings apply, that entry shows in parentheses how they reached your machine.

The line tells you which files were read, not which file supplied each key. For entries Claude Code rejected, run claude doctor in your terminal. A broken file shows up in one of two ways at the start of an interactive session:

• Settings Error: a file has invalid JSON or a value the schema rejects. Claude Code offers to fix it with Claude's help, exit, or continue without that file.
• Settings Warning: only some entries fail, such as a malformed permission rule. Claude Code skips those and keeps the rest of the file.

A non-interactive -p run shows no dialog. It skips the broken file or values and carries on, so run claude doctor afterward to see what it dropped.

Reference: which file wins

When a key is set in more than one place, Claude Code uses the value from the highest level:

A managed model is a starting default, not a lock. The locks are availableModels and deniedModels.

Reference: lists merge instead of overriding

Set the same list key, such as permissions.allow, in several files and Claude Code combines the lists, so each file adds entries without removing another's. Four model keys follow their own rules:

Permission rules add one more layer. An allow rule in your local file doesn't outrank an ask rule from a project or managed file, which is why you can still get a prompt after choosing "Yes, and don't ask again." Anthropic's permissions page covers how allow, ask and deny combine.

Reference: when a stricter value beats managed

For a few keys that restrict a session, Claude Code honors the stricter value even from a level that normally can't override managed settings. Three of them:

Anthropic's page lists the rest, including remoteControlAtStartup, which a project file can switch off but not on.

Reference: where managed settings live

A file-based policy goes in a system directory:

A managed-settings.d/ folder beside the file lets several teams own parts of one policy. Claude Code merges managed-settings.json first, then each .json file in the folder in alphabetical order. Anthropic notes that on WSL, /etc/claude-code is user-writable too, and that Claude Code doesn't read the old Windows path under C:\ProgramData.

Cloud sessions are the other exception to keep in mind. They run on a fresh clone, so they read a committed .claude/settings.json in a single-repository session but never your user or local file. A managed settings file on your laptop doesn't reach them either; server-managed settings from the admin console do.

Troubleshooting

Frequently asked questions

Where is the Claude Code settings.json file?

Your personal file is ~/.claude/settings.json, in the .claude folder in your home directory. A project's shared file is .claude/settings.json inside the project, and your personal override for that project is .claude/settings.local.json beside it. Installing Claude Code creates none of them; create them yourself or let Claude Code write them.

Which Claude Code settings file takes priority?

The highest level that sets a key wins: managed settings, then JSON passed with the settings flag at launch, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List keys such as permissions.allow are the exception, because they merge across files instead of replacing each other.

What's the difference between settings.json and settings.local.json?

.claude/settings.json is the team's file: commit it and everyone who clones the repository gets it. .claude/settings.local.json is yours alone in that project. It sits above the team file, Claude Code keeps it out of git when it creates it, and its allow rules skip the trust step while it stays untracked.

Do I need to restart Claude Code after editing settings?

Usually not. Claude Code watches its settings files and applies most edits, including permissions and hooks, to the running session. A few keys are read only at start, such as model and effortLevel, so use /model or /effort to change those mid-session. Managed settings arrive on a schedule.

Can I put comments in Claude Code's settings.json?

No. Settings files are strict JSON, so a // comment or a trailing comma is a syntax error. Claude Code reports it as a Settings Error at the next interactive start and offers to fix the file, exit, or continue without it. Add the $schema line to get validation in your editor.

Why don't my project's allow rules work for a new teammate?

Allow rules in a committed .claude/settings.json wait until each person accepts the workspace trust dialog for that folder. Deny and ask rules apply right away. If trust is accepted and a key still doesn't apply, check whether the settings reference marks it as user, local or managed only.

How do I see which Claude Code settings are in effect?

Run /status and read the Setting sources line on the Status tab. It lists every settings file that loaded and how managed settings reached you. It doesn't show which file supplied each key, so run claude doctor for rejected entries and check the key's own entry in Anthropic's settings reference.

Put the rules behind your settings in writing

A settings file says what Claude Code may do. It doesn't say why, and Claude works better when the reasoning lives somewhere it reads. Our guide to compound engineering for Claude Code shows how to build those written rules up one fix at a time. For the guardrails that run on top of these files, see our Claude Code hooks guide, and for how a team splits rules between guidance and enforcement, Claude Code best practices for a team.