TopolearnPutting a setting in the right file decides whether it applies to you, your team or everyone, and avoids surprises.
Claude Code reads JSON settings files from several places. Each is a scope, deciding who the setting affects:
- User:
~/.claude/settings.json, for you in every project. - Shared project:
.claude/settings.json, committed to git so the whole team gets the same permissions, hooks and plugins. - Project local:
.claude/settings.local.json, your personal overrides for one project. Claude Code keeps it out of git when it creates it. - Managed: deployed by your organization; nobody can override it.
When the same key is set in several places, the order from highest to lowest is: managed, then the --settings command-line flag, then project local, then shared project, then user. Lists such as permission rules are merged across files rather than replaced, so a team deny plus your personal allow both apply.
Other things that look like settings but live elsewhere: CLAUDE.md files (instructions), .mcp.json (project MCP servers), and the .claude/ folder holding skills, agents and rules.
Practical guidance:
- Team-wide safety rules and shared hooks go in
.claude/settings.jsonand get code review like code. - Personal conveniences (your editor, extra allowed commands) go in the user or local file.
- Files are strict JSON: no comments, no trailing commas. Add the
$schemaline for autocomplete in your editor. /configopens an interactive settings screen;/statusshows which setting sources loaded.claude --settings '{...}'applies settings for one run, handy in scripts.
Example
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"],
"deny": ["Read(./.env)", "Read(./.env.*)"],
"defaultMode": "default"
},
"env": {
"NODE_ENV": "development"
}
}Remember
- User ~/.claude/settings.json, project .claude/settings.json, local .claude/settings.local.json, plus managed
- Precedence: managed > --settings > local > project > user; lists merge
- Commit the shared project file; keep personal tweaks in local or user
Watch out for
- Putting personal allow rules in the committed .claude/settings.json, silently granting them to every teammate.