Settings configuration fallback hierarchy in Claude Code

Link copied

Attach video time

Most of your settings get written for you. Pick a model with /model, approve a permission with "Yes, and don't ask again," and Claude Code saves that choice to a settings file on its own.

You'll open these files by hand when you want to do something that the user interface doesn't offer you, such as controlling which model should be used as default globally versus a specific project.

The three files

~/.claude/settings.json — your personal settings, applied to every project on your machine. This is where /model saves your default.

.claude/settings.json — settings for a single project, committed to version control so your teammates get them too.

.claude/settings.local.json — settings for a single project, on your machine only. Permissions you approve during a session land here as allow rules. This one stays out of your commits.

They all use the same format:

{
  "model": "opus",
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

Be sure to use model aliases like opus or sonnet rather than a full model name, so you won't have to update them when new models come out (unless you want that level of specificity).

Which file wins

More specific beats more general, and local beats shared.

So settings.local.json overrides your project's settings.json, which overrides your personal settings in ~/.claude. Most settings are stored in the global ~/.claude/settings.json file.

But if your team's settings.json sets the model to Sonnet and you'd rather run Opus, put it in settings.local.json and only your sessions change. Similarly, if you'd like all projects to use Opus by default but want the model to default to Fable in a specific project, you can set that in your project's settings.json file.

Two things sit above all of your files: flags you pass at launch, like claude --model opus, which last only for that session, and settings your organization deploys centrally, if you're on a managed setup.

When a setting doesn't take effect

Run /status and look at the Setting sources line. It lists every settings file that loaded for the session, which beats guessing where your value came from.

You can also verify which settings are active by toggling over to Config and then searching the settings for the related configuration value.