Claude Code settings: which file wins and why

Claude Code settings come from four files, and the file a setting sits in decides who it applies to: only you, everyone in a project, or everyone in your organization. Put a setting in the narrowest file that fits and the precedence question mostly answers itself.

This guide covers the user, shared project, project local and managed files, the order they win in, the checks that show what loaded, and three settings worth changing first. It applies to the terminal, the VS Code and JetBrains extensions and the desktop app, which all read the same settings files. If settings also decide how fast you burn quota, read Claude Code usage limits next.

1. Pick the file by who it should affect

Which file should a setting go in? Ask who needs it.

The shared project file is the one to commit: in a git repository, commit it so teammates get it. Use it for team permissions, hooks, plugins and the environment variables the project needs. Use the user file for personal preferences such as theme, editor mode and default model.

Installing Claude Code doesn’t create any settings file. Claude Code writes them when you act:

There is also a fifth file, ~/.claude.json, that Claude Code writes for itself. It holds your account details, MCP server configurations and per-project trust decisions, so leave it alone.

2. Know which file wins

When two files set the same key, Claude Code uses the value from the highest level that sets it.

The clearest case for you is the local file: Claude Code applies that file over the committed .claude/settings.json. If the team file sets claude-sonnet-5 as the model and you want Opus, put claude-opus-5-5 in your local file and only your sessions change.

{
  "model": "claude-opus-5-5"
}

Managed settings sit above all of it. If your organization manages Claude Code, some settings are decided for you and nothing you put in your own files changes them. The --settings flag also has a fixed place: above your user, project, and local files and below managed settings.

The same key, spinnerTipsEnabled, shows each case. You set it to false in your user file, then something else sets it to true:

List keys behave differently. A list such as permissions.allow set in more than one file is combined instead of overridden, so each file adds entries without removing another file’s.

Where a setting lives also decides whether anyone else gets it. A shared project file reaches a teammate’s clone and a cloud session only if you commit the file to version control. Your user file reaches neither.

3. Check what loaded with /status

How do you confirm a file took effect? Run /status inside Claude Code. The Setting sources line names the managed source that applies to you, and it lists each file loaded for the session, which is how you confirm a file you just saved loaded. It does not show which file supplied each key.

/status          # Setting sources: the files loaded this session
claude doctor    # entries Claude Code rejected, with the reason

Settings files are 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. Add a $schema line and editors that support JSON schema, including VS Code and Cursor, give you autocomplete and inline validation. The schema can lag behind new releases, so a warning on a recently documented key doesn’t mean your configuration is invalid.

4. Change a setting the way that fits

You have three routes.

1. The /config menu. It lists a short set of personal options such as theme, editor mode and verbose output, and saves them for you. To set one option without the menu, pass key=value, such as /config verbose=true. The VS Code chat panel and the desktop app don’t open it, so edit a file there.
2. Edit a file. Open the file for the scope you want and add the key. Claude Code watches the files and applies most edits, including permissions and hooks, without a restart.
3. Override for one session. Your files stay untouched. Use --settings with JSON inline or a file path, a per-key flag such as --model, or an environment variable such as ANTHROPIC_MODEL.

For example, to start one session on Opus without changing your default:

claude --settings '{"model": "claude-opus-5-5"}'

Standing instructions are not a settings key. Claude Code’s system prompt isn’t published, so use CLAUDE.md files or the —append-system-prompt flag. If one repo of skills should serve more than one tool, see how to share one skills repo between Claude Code and Codex.

5. Start with these settings

Three changes pay off first, and each maps to a scope above.

• Allow your routine commands. Rules under permissions name a tool and what it may do. Allowing your lint and test commands in the user file stops the repeated prompts.
• Deny secret files. A deny rule on .env files keeps Claude Code from reading them.
• Pin the model per project in the local file. It overrides the team’s choice for you alone.

The docs show the first two in one user file:

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

That block goes in ~/.claude/settings.json, and the commands inside it are the docs’ example project’s, so swap in your own. Model choice also changes how quickly a weekly limit runs out, which pacing your Claude subscription covers.

In a committed file, some keys wait for each teammate to trust the folder before they apply:

Verdict

Put team rules in the committed .claude/settings.json, personal preferences in ~/.claude/settings.json, and your own overrides for one project in .claude/settings.local.json, which wins over the committed file. Run /status after every edit, and treat anything your organization manages as fixed.

Set up Claude Code today: read the settings docs at code.claude.com