lockstep
5 min readNaman Jain

Claude Code settings.json: locations, precedence, examples

Where Claude Code's settings.json files live, which one wins, how lists merge, the keys worth setting, and copy-paste examples for a personal and a team file.

You allow git diff in your settings, a teammate's Claude Code still asks for permission every time, and nobody is sure which of four JSON files is in charge. Claude Code's settings are simple once you know where each file lives and which one wins.

This guide covers the files, the order they apply in, the keys worth setting, and two examples, from Anthropic's settings documentation and example settings files, checked on 16 November 2026.

The settings files

FileApplies toShared?
~/.claude/settings.jsonYou, in every project on your machineNo
.claude/settings.jsonEveryone in this projectYes, when committed
.claude/settings.local.jsonYou, in this project onlyNo; Claude Code adds it to your git excludes when it writes it
Managed settingsEveryone in your organizationDeployed by admins

Managed settings arrive as a managed-settings.json file, an MDM policy, or server-managed settings from the claude.ai console. The admin side is covered in Claude Code managed settings.

There is a fifth file, ~/.claude.json, that Claude Code writes for itself. It holds account details, MCP server configurations, per-project state like trust decisions, and keys that /config saves. You don't need to edit it. To keep home-directory files somewhere else, set CLAUDE_CONFIG_DIR.

Which file wins

When the same key appears in several places, the highest level wins:

  1. Managed settings. Nothing in your files overrides a managed key.
  2. --settings passed when starting claude, for that session only.
  3. .claude/settings.local.json, your personal project settings.
  4. .claude/settings.json, the team's shared settings.
  5. ~/.claude/settings.json, your personal settings everywhere.

Two details matter:

  • Lists merge. Permission rules and other list settings combine across levels instead of replacing each other. The team's allow list and your own both apply.
  • Environment variables aren't a level. When a behavior has both a shell variable and a settings key, which one wins is decided per pair. An env block inside a settings file is an ordinary key and follows the levels above.

Run /status in a session to see which sources loaded, and to spot a broken file.

Keys worth knowing

KeyWhat it does
$schemaPoints to https://json.schemastore.org/claude-code-settings.json for editor autocomplete
modelThe model sessions start with
permissions.allow / permissions.denyTool calls that skip the prompt, or are always blocked
envEnvironment variables for every session
hooksCommands that run on lifecycle events
autoMemoryEnabledTurns auto memory on or off
autoMemoryDirectoryMoves auto memory; must be an absolute path or start with ~/
claudeMdExcludesCLAUDE.md files to skip, for example other teams' files in a monorepo
includeGitInstructionsTurns off Claude Code's built-in git and PR guidance
attributionSets the attribution text on commits and PRs
cleanupPeriodDaysHow long old session transcripts are kept

For permission rule syntax and modes, see Claude Code permissions. For the status bar, see Claude Code status line. For response style, see Claude Code output styles. The JSON schema can lag behind new releases, so a validation warning on a recently documented key doesn't always mean it's wrong.

Example: your personal settings

~/.claude/settings.json:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": ["Bash(git diff *)", "Bash(git status)"]
  },
  "cleanupPeriodDays": 20
}

Settings files don't accept comments, so keep notes elsewhere.

Example: a team's shared settings

.claude/settings.json, committed:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"],
    "deny": ["Bash(git push *)"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Each teammate can still add personal exceptions in their own .claude/settings.local.json without a commit. Some committed settings, such as hooks, wait until each teammate trusts the folder. For more hooks to drop in, see Claude Code hooks: 6 examples.

Changing settings

  • /config opens a menu for common settings. Most save to your user file; standing permission approvals, such as "Yes, and don't ask again", save to .claude/settings.local.json.
  • Edit the file directly, then run /status to confirm it loaded.
  • For one session, pass --settings with JSON or a file path, or use a flag like --model.

When a setting doesn't apply

SymptomLikely cause
Your value is ignoredA higher level, often managed settings, sets the same key
A committed setting doesn't reach a teammateThey haven't trusted the folder yet, or the key can't be set from a repository file
Nothing from the file appliesThe JSON is invalid; /status reports it
An MCP server isn't in settings.jsonMCP servers live in ~/.claude.json or .mcp.json, not settings files

For MCP configuration specifically, see Claude Code MCP setup.

What settings can't hold

Settings control how Claude Code behaves: models, permissions, hooks. They can't hold what your team decided about the product, such as which customers get an exception or which API version is being retired. Those change too often and come from outside the repository.

Where Lockstep fits

Lockstep keeps those decisions current and briefs Claude Code on them at the start of each session. Onboarding adds its MCP server and a session-start hook to your Claude Code configuration, and npx lockstep-cli uninstall removes the entries it added. Decisions come from PRDs, Slack, and pull requests, and become binding when their owner approves them.

Session briefings work with Claude Code today. See how it works.

Sources checked 16 November 2026

For organization-wide settings and managed CLAUDE.md, see how Claude Code memory works. For choosing between hooks, skills, and MCP, see CLAUDE.md vs skills vs hooks vs subagents. For a company-wide rollout, see how to roll out Claude Code to an engineering team.

Frequently asked questions

Where is the Claude Code settings.json file?
Your personal settings are in ~/.claude/settings.json and apply to every project. Team settings are in .claude/settings.json inside the project and are shared when committed. Your personal settings for one project are in .claude/settings.local.json, which Claude Code keeps out of git.
Which Claude Code settings file wins?
Managed settings from your organization win over everything. Then settings passed with --settings for one session, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List settings such as permission rules merge across levels instead of replacing each other.
Is there a JSON schema for Claude Code settings?
Yes. Add "$schema": "https://json.schemastore.org/claude-code-settings.json" at the top of the file for autocomplete and validation in editors that support JSON schema. Anthropic notes the schema can lag behind new releases.
What is the difference between settings.json and ~/.claude.json?
settings.json files hold settings you edit: permissions, hooks, model, environment variables. ~/.claude.json is a file Claude Code writes for itself, holding account details, MCP server configurations, per-project state such as trust decisions, and keys that /config writes. You don't need to edit it.
How do I check which settings loaded?
Run /status inside Claude Code. It shows the setting sources that loaded and reports a broken file. Use /config to change common settings from a menu.

Keep reading