Claude Code Settings Reference

Problem: Most Claude Code pain has one root cause. Your config does not line up with how you work. You rubber-stamp bash commands all day, team defaults never load, or a key you edited yesterday does nothing.

The cure is knowing the settings system. Not only the keys, but the precedence rules that pick a winner when two scopes disagree.

Quick Win: Drop a $schema line into settings.json and every editor that understands JSON schema lights up with autocomplete and inline checks. VS Code, Cursor, and anything else with schema support all benefit.

The Five-Scope Precedence Chain

Settings follow a fixed pecking order. Knowing it is the gap between "why did my change not land" and "oh, wrong file."

Scope Precedence (Highest to Lowest)

Higher scopes always beat lower ones. Full stop. A managed rule from IT that blocks Bash(curl *) is unreachable by any personal or project file.

Picking the Right Scope

Managed fits organizations that need rules with no escape hatch:

• Security policies (block credential access, forbid destructive commands)
• Compliance that must apply to every engineer and every repo
• Standard hooks or MCP configs rolled out by IT

Command line flags handle one-shot overrides within a single session:

• Trying a different model: claude --model claude-sonnet-4-5-20250929
• Granting extra permission headroom for one specific job
• Running with the --debug flag

Local is your private sandbox for a given repo:

• Quietly override a project rule that does not fit your machine
• Try out a hook before you pitch it to the team
• Paths unique to this machine (where your SSH key lives, which port the local proxy runs on)

Project is the place where the team lines up:

• Permission rules everyone follows
• Shared hooks for auto-format and lint
• MCP server configs every teammate needs
• CLAUDE.md instructions that describe the project

User is your own defaults:

• Language, theme, and the output style you prefer
• Plugins you want on in every repo
• Global permission rules (like a blanket deny on ~/.ssh)

Managed Settings Paths by OS

Managed files need admin rights and sit outside any user home directory:

Two files live in those folders. managed-settings.json holds the settings, managed-mcp.json holds MCP servers.

Every knob in Claude Code lives at a known file path in each scope:

Settings Reference

General Settings

Permission Settings

The keys below all nest inside the "permissions" object.

Evaluation order: Deny gets the first pass. Ask is next. Allow goes last. The first rule that matches is the one that lands.

Rule syntax examples:

Sandbox Settings

The keys below nest inside the "sandbox" object and govern how bash commands are isolated.

Attribution Settings

The keys below nest inside the "attribution" object and decide how git attributes Claude's work.

Blank out either key with "" and the matching line disappears from git. The legacy includeCoAuthoredBy key still works, though it is now deprecated.

Plugin Settings

Four source types exist. github points at a repo. git accepts any URL. directory uses a local path while you are developing. hostPattern does regex matching on hostnames.

MCP Server Settings

Authentication and Provider Settings

Hook and Advanced Settings

Environment Variables

Claude Code reads about 70 env vars. Most are edge cases. A working set of roughly 20 is all you see in day-to-day use.

Model and Provider

The alias vars (ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL) come in handy whenever your org points a fine-tuned model at the stock alias names.

Performance Tuning

Privacy and Telemetry

Session Control

Two ways exist. Export them from your shell profile, or drop them into the "env" object of settings.json so they survive sessions without any shell rc edits.

Working Out Config Conflicts

Most of the classic config headaches go away once you know which scope trumps which.

Case 1: A permission rule disagrees between scopes

Your user config allows Bash(curl *). The project config denies it. Who comes out on top? Project sits at priority 4 and user sits at priority 5, so the block holds. If curl is genuinely needed on your own machine, put the allow rule into .claude/settings.local.json instead. Local at priority 3 outranks project at priority 4, and the local allow then overrides the blocked rule.

Case 2: A managed file shoots down a project rule

Your team's settings.json in the project allows Bash(rm -rf *). IT then ships a managed file that blocks that same command. Managed is the winner. Always. Nothing in a user, local, or project file can reach above managed rules. The design is on purpose, and compliance is the reason.

Case 3: Trying something out locally

You want to pilot a new hook before offering it to the team. Put it in .claude/settings.local.json. It outranks the shared .claude/settings.json and stays on your machine only.

Case 4: Two scopes merging

Scopes do not wipe each other out wholesale. They stack. User config allowing Bash(git status) and project config allowing Bash(npm run lint) give you both rules active at once. The merge stitches permission arrays together. If the same key carries a different value at two scopes, the higher scope is the one that sticks for that single key.

Case 5: An env var exported from the shell and listed in settings.json

Export ANTHROPIC_MODEL from your shell and also list it in the env object of settings.json, and the shell export is the value Claude Code uses.

How Settings Plug Into the Rest of the System

CLAUDE.md files hold the instructions Claude loads at startup, plus the background it needs. A clean mental model: settings say what Claude is allowed to do, CLAUDE.md says what Claude should know.

MCP servers plug new tools into Claude. Their config lives in its own files (.mcp.json at project level, ~/.claude.json at user level). settings.json is the place that decides which of those servers are approved and which are blocked.

Hooks live inside settings.json under the hooks key. Each one runs a shell command, or sends an LLM prompt, when a lifecycle event fires.

Plugins also run through settings.json, via enabledPlugins and your marketplace list.

Subagents are plain Markdown files. User ones go in ~/.claude/agents/, project ones in .claude/agents/.

Backups and Recovery

Every time a config file changes, Claude Code writes a timestamped backup. The last five copies per file stick around. A bad update no longer means digging through git reflog. The previous working version sits next to the broken one.

Getting Started

New to Claude Code settings? Run through this short list in order.

1. Permission rules at the project level. Block any read on .env and other secret files. Allow the build or test commands you reach for every day
2. A PostToolUse hook that auto-formats on save. This one entry destroys approval fatigue faster than anything else
3. Attribution settings if the Co-Authored-By line needs tweaking or hiding
4. User defaults for the preferences you want active across every repo you touch
5. A CLAUDE.md file carrying project context and your code conventions