# Settings a team can share

Claude Code reads settings from several scopes and merges them by a fixed order. Knowing which file wins, and what belongs in git, is what keeps a team's rules from becoming one person's habits.

## Four files and one that is not yours

Claude Code has four settings scopes:

- **User**: `~/.claude/settings.json`, yours across every project.
- **Shared project**: `.claude/settings.json`, committed to the repository.
- **Project local**: `.claude/settings.local.json`, yours inside this one project.
- **Managed**: set by an organization through a file, MDM or server-managed settings.

A fifth file, `~/.claude.json`, is not one you edit. Claude writes it itself: account, MCP configs, trust state.

The split is the whole point. A team rule belongs in a file the team shares. A personal preference belongs in a file only you have.

## Who wins

When scopes disagree, the order from highest to lowest is: managed, command line (`--settings`), project local, shared project, user.

```flow
Managed settings
Command line: --settings
Project local
Shared project
User
```

Arrays are the exception to "highest wins". Lists such as `permissions.allow` merge across scopes, so a rule added at user level and one added in the project both apply.

The model is a good example of a small trap. `ANTHROPIC_MODEL` beats the `model` setting from any file, while `ANTHROPIC_DEFAULT_MODEL` only applies when no file sets one. And a few keys honour a stricter value from a lower scope even over managed settings, such as `disableClaudeAiConnectors: true` or `permissions.blockReadsOutsideWorkingDirectories: true`. The stricter value wins.

**Question:** A user setting allows one command and the project settings allow another. What applies?

- Only the project one, because it is higher
- Only the user one
- Both, because permission arrays merge across scopes
- Neither, they cancel out

**Answer:** Both, because permission arrays merge across scopes. Arrays such as permissions.allow merge across scopes instead of replacing each other.


## What goes in git

Commit `.claude/settings.json` for rules the team agrees on: deny rules for secrets, the allowlist for the commands everyone runs, shared hooks. Keep `.claude/settings.local.json` for personal overrides.

Claude does some of the work for you. The first time it writes `settings.local.json` it adds the file to your global git excludes. In a git repository the local file lives at the repository root (or the main checkout root for worktrees).

There is a trust detail that matters for a new teammate. Committed deny rules apply immediately. Committed allow rules wait until each teammate accepts the folder trust dialog.

> **Some settings ignore the project file**
`defaultMode: "auto"` or `"bypassPermissions"` in a project settings file is silently ignored. Only user or managed settings honour it. Do not rely on committing a permission mode for the team.


"Yes, and don't ask again" writes an allow rule to `.claude/settings.local.json`, so personal approvals stay personal. An allow there does not outrank an `ask` rule from a project or managed file.

## Checking what loaded

Settings are strict JSON. A comment or a trailing comma triggers a Settings Error dialog at start. Add `"$schema": "https://json.schemastore.org/claude-code-settings.json"` and your editor validates the file as you type.

```terminal
$ claude
> /status
* Shows which settings sources loaded
> /config model=sonnet
* Sets the value directly
$ claude doctor
* Lists entries that were rejected
# Most edits apply live: permissions, hooks and apiKeyHelper need no restart.
```

When behaviour differs between two people on a team, `/status` is the first thing to compare, then `claude doctor`.

> **Cloud sessions skip your files**
In cloud sessions user and local settings are not read at all, and managed files on your device do not reach them. If you rely on a personal setting, it will not be there. Put what a cloud run needs in the shared project file.


## Moving and recovering

`CLAUDE_CONFIG_DIR` moves settings, history and plugins elsewhere. A corrupted `~/.claude.json` is backed up to `~/.claude/backups/`, and the five most recent `.claude.json.backup.<timestamp>` copies can be restored. `/model` saves the model as your default; pressing `s` in the picker switches without saving.

> **Audit your own split**
Open `.claude/settings.json` in a repository you work on and ask of each line: would a new teammate want this? Anything that is really a personal habit moves to `.claude/settings.local.json`. Anything every contributor needs, such as a deny rule for `.env`, belongs in the committed file.


**Question:** Which file should hold your own preferred shortcuts for approving commands in one project?

- ~/.claude.json
- .claude/settings.json
- .claude/settings.local.json
- Managed settings

**Answer:** .claude/settings.local.json. Project local settings are personal to you and added to git excludes. The shared project file is for rules the team agrees on.