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.
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.
A user setting allows one command and the project settings allow another. What applies?
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.
"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.
$ 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.
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.
Which file should hold your own preferred shortcuts for approving commands in one project?
Chapter complete
You've finished chapter 5 of 6 in Parallel and unattended.
When no one can answer a prompt, the permission rules are the only supervisor left. The safe setup is narrow allow rules, hard deny rules, a capped run and nothing valuable within reach.
Next chapter