Which Claude Code settings file wins

You change a setting, nothing happens, and you cannot tell why. Usually the same key is set in a second file that sits above yours. This page lists the files and the order.

The four sources

• User~/.claude/settings.json. You, in every project on this machine. Good for personal preferences and your own permission rules.
• Shared project.claude/settings.json inside the project. Everyone who works in that folder. In a git repository you commit it so teammates get it too.
• Project local.claude/settings.local.json. You, in this one project. For personal overrides and for trying something before you share it.
• ManagedDeployed by an organization. You do not create or edit it.

On Windows, ~/.claude means %USERPROFILE%\.claude. Installing Claude Code creates none of these files. The /config menu writes the user file the first time you change an option stored there, and a standing approval such as "Yes, and don't ask again" on a permission prompt writes the local file.

There is a fifth file, ~/.claude.json. Claude Code writes it for itself, and it holds things like account details, MCP server configuration and trust decisions. You do not need to edit it.

Which one wins

When the same key is set in more than one place, Claude Code uses the value from the highest level. From highest to lowest:

1. Managed settings from your organization.
2. The command line: JSON you pass with --settings for one session.
3. Project local: .claude/settings.local.json.
4. Shared project: .claude/settings.json.
5. User: ~/.claude/settings.json.

An example from the documentation: your team's shared file turns a tip on, and your own user file turns it off. The project value wins, so you see the tip in that project and nowhere else. To get your value back in that project, put it in .claude/settings.local.json, which sits above the shared file and changes nothing for your teammates.

Lists add up

For list keys such as permissions.allow, Claude Code combines the entries from every file instead of choosing one. Each file can add rules without removing another file's. A few model-related keys follow their own rules, so check the entry for the key you care about.

Environment variables are not a level

Whether a shell variable or a settings key applies is decided key by key, not by level. For example, ANTHROPIC_MODEL in your shell overrides the model key from any file. The page for each key says which one applies.

A file to start from

Settings files are strict JSON. A comment or a trailing comma is an error. This example lets Claude Code run your lint and test commands without asking and stops it reading .env files. Put it in ~/.claude/settings.json:

{
  "$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 is optional. It gives editors that support JSON schema autocomplete and warnings. The schema can lag behind the newest releases, so a warning on a recently added key does not mean your file is wrong. Change the commands to ones your project really uses.

Check what loaded

• Run /status. The Setting sources line lists the settings files Claude Code loaded in this session. It does not say which file supplied each key.
• Run claude doctor to see entries Claude Code rejected.
• If a file has invalid JSON, Claude Code shows a Settings Error at the start of an interactive session. If only single entries are wrong, it skips those and keeps the rest.
• Most edits to a running session apply without a restart, including permissions and hooks. A few keys are read only once at startup.

Why a setting does nothing

• A higher level sets the same key. Look at the order above.
• A project allow rule waits until each teammate trusts the folder. deny and ask rules apply right away.
• Some keys never take effect from the shared project file. The documentation marks those in its settings reference. The permission modes auto and bypassPermissions do not take effect from project or local settings.
• The file is not where you think it is. In a cloud session only the shared project file is read, not your user or local file.
• /config works in the terminal. The VS Code chat panel and the desktop app do not open it, so edit a file or use those apps' own settings.

Try one session without saving

claude --settings '{"permissions": {"deny": ["Read(./.env)"]}}'

That applies for one session and writes nothing to disk.

Limits

• Keys, defaults and file locations change between versions. The settings reference is the authority.
• The shared file is committed, so everyone who clones the repository gets it. Keep personal overrides in the local file.
• This is general information about a tool, not a security audit of your setup.

This follows Anthropic's settings documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case.

For the rules inside permissions, see a starter list of permission rules. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.

See also: Claude Code in a large codebase.