Claude Code settings.json: scopes, precedence, and troubleshooting

Who this is for and what you will be able to do

This guide is for developers who need to know where a settings.json entry belongs, which file wins when two files set the same key, or why a change did not take effect. When you finish, you will know which of the four settings files reaches which people, how to resolve a key that is set in several places, and how to confirm what loaded.^[1]

What settings control

Settings are JSON keys that change how Claude Code behaves. They control the model Claude Code starts with, which actions run without asking, which files it cannot read, and what the organization enforces.^[1]

Claude Code reads settings from JSON files such as ~/.claude/settings.json. The file a setting is saved in decides who it applies to.^[1]

The four settings files and their scope

The user file, ~/.claude/settings.json, applies to you in every project on the machine. It suits personal preferences such as theme, editor mode, default model, and your own permission rules.^[1]

The shared project file, .claude/settings.json, applies to everyone who works in the folder that contains it. In a git repository, commit it so teammates receive the same settings. It suits team permissions, hooks, plugins, and the environment variables a project needs.^[1]

The project local file, .claude/settings.local.json, applies only to you, and only in that project. Claude Code keeps it out of git when it creates the file.^[1]

Managed settings are deployed by the organization to everyone it reaches, and they carry security policy and compliance requirements.^[1]

Installing Claude Code does not create a settings file. A file exists because your organization deployed it, because you created it, or because Claude Code wrote it. Changing a user-level option in the /config menu makes Claude Code write ~/.claude/settings.json. Choosing "Yes, and don't ask again" on a permission prompt for the first time makes it write .claude/settings.local.json.^[1]

On Windows, ~/.claude means %USERPROFILE%\.claude. To keep the home-directory files somewhere else, set CLAUDE_CONFIG_DIR.^[1]

Changing a setting for yourself only

To change a setting for yourself in one project without affecting teammates, save it in .claude/settings.local.json. Claude Code applies that file over the committed .claude/settings.json.^[1]

The /config menu or a direct edit

The /config menu lists a short set of personal options, such as theme, editor mode, and verbose output. It does not list every key. Select an option and Claude Code saves it. To set one option without opening the menu, type a form such as /config verbose=true.^[1]

When you edit a file by hand, remember that settings files are strict JSON. A // comment or a trailing comma is a syntax error, and Claude Code reports it as a Settings Error at the next start. Here is an example that lets lint and test commands run without asking and blocks reading .env files:^[1]

``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.*)" ] } } ``^[1]

After you save, run /status inside Claude Code and check the Setting sources line, which lists each settings file loaded for the current session.^[1]

Changing a setting for one session

To try a value without saving it, set it at startup. The --settings argument accepts JSON. It applies above the user, project, and local files, and below managed settings. It cannot set Managed or Global config keys.^[1]

Some keys have their own flag. --model sets model, and --effort sets effortLevel. The environment variable ANTHROPIC_MODEL also sets model.^[1]

To start one session on Opus without changing your default, pass the setting inline:^[1]

``bash claude --settings '{"model": "claude-opus-5-5"}' ``^[1]

In the /model picker, pressing s switches the model without saving it as your user default.^[1]

When an edit takes effect

Claude Code watches the settings files and reloads them. Most edits therefore reach the running session without a restart, including edits to permissions, hooks, and apiKeyHelper. A few keys are read only once, at session start, so an edit to one of them does not reach a running session. Restart the session for those.^[1]

Which value wins

Managed settings sit at the top, so nothing in your own files or --settings can override a managed key. User settings sit at the bottom, so any higher level that sets the same key overrides them. When a value surprises you, first find every layer that sets the key, then read them from the top down.^[1]

Precedence runs from highest to lowest: managed settings, the command line, project local settings, shared project settings, and user settings. A key set at a higher level overrides the same key set lower down.^[1]

Environment variables are not a level in this stack. Each variable and key pair is resolved on its own.^[1]

List keys work differently. When permissions.allow is set in more than one file, Claude Code combines the lists rather than choosing one, so each file can add entries without removing another file's entries.^[1]

A few security-sensitive keys are an exception. A restrictive value from any scope is honored even when managed settings set the opposite. For example, disableClaudeAiConnectors set to true stays on.^[1]

When a setting does not apply

Two questions cover most cases: is a higher level setting the same key, and did this file load at all? The first is answered by the precedence order, and the second by /status. Then match your symptom to a cause below.^[1]

• A Settings Error means a user, project, or local file has invalid JSON or a rejected value. In an interactive session, Claude Code shows a dialog that lets you fix the file, exit, or continue without the broken settings.^[1]
• A Settings Warning means only individual entries fail, such as a malformed permission rule. Claude Code skips those values and keeps the rest of the file in effect.^[1]
• A -p run shows no dialog. It skips a broken user, project, or local file, or the broken values in it, and continues with the rest.^[1]
• Values auto and bypassPermissions for permissions.defaultMode do not take effect from project or local settings. Put them in user or managed settings.^[1]
• The allow rule saved by "Yes, and don't ask again" lives in the local file, and it does not outrank an ask rule from a project or managed file.^[1]

To list entries that Claude Code rejected, run claude doctor.^[1]

Next steps

For every settings key, with its scope, default, and example, read the settings reference in Claude Code's official documentation.^[1]