CONFIGURATION REFERENCE

Claude Code Settings & Permissions

How to configure Claude Code with settings.json and environment variables: the scope system, precedence, permissions, and the settings you'll reach for most. Run /config to edit these from inside a session.

Configuration scopes

Where a configuration lives determines who it applies to and whether it is shared. When the same key appears in several scopes, the higher-priority scope wins (scalars override; arrays merge).

Managed

Org policy deployed by IT (server-managed, MDM plist/registry, or managed-settings.json). Highest precedence — cannot be overridden by anyone, not even CLI args.

Shared with team ✔ (deployed by IT)

User

Personal, global settings that apply across all your projects.

~/.claude/settings.json · not shared

Project

Team-shared settings checked into source control for all collaborators on the repo.

.claude/settings.json · shared ✔ (committed to git)

Local

Personal overrides for one repo — experimentation and machine-specific tweaks. Gitignored when Claude Code creates it.

.claude/settings.local.json · not shared

Files & locations

Scopes apply to many features, each with its own user / project / local location.

Settings

The JSON settings file for each scope.

~/.claude/settings.json · .claude/settings.json · .claude/settings.local.json

Subagents

Markdown files with YAML frontmatter defining specialized agents.

~/.claude/agents/ · .claude/agents/

MCP servers

User/local servers live in ~/.claude.json; project servers in .mcp.json.

~/.claude.json · .mcp.json

CLAUDE.md

Memory / instructions loaded at startup.

~/.claude/CLAUDE.md · CLAUDE.md · CLAUDE.local.md

~/.claude.json

OAuth session, user/local MCP config, per-project state and caches — not settings.json.

global config store

Settings precedence

Settings apply in order of precedence, highest first. Higher scopes win for scalar values.

1Managed settings — IT-deployed policy. Cannot be overridden by anything, including command-line arguments.
2Command-line arguments — temporary per-session overrides, e.g. --settings <file-or-json>.
3Local project settings — .claude/settings.local.json (personal, per-repo).
4Shared project settings — .claude/settings.json (team, in source control).
5User settings — ~/.claude/settings.json (personal global; applies when nothing else specifies the key).

Scalars override, arrays merge. A scalar (like model) from a higher scope replaces the lower one; array settings like permissions.allow are concatenated and de-duplicated across scopes.

Two array exceptions: fallbackModel is an ordered chain supplied whole by the highest scope that sets it; a managed availableModels list applies as-is and can't be extended.

Reload: most keys (permissions, hooks, apiKeyHelper) reload live. model and outputStyle are read at start — use /model to switch mid-session.

Permission modes

permissions.defaultMode sets how Claude Code asks before acting. The --permission-mode flag overrides it for one session.

default

Prompt for permission the first time each tool is used. Aliased as manual (v2.1.200+).

safest interactive default

acceptEdits

Automatically accept file edits without prompting.

fast editing loops

plan

Plan mode — analyze and design without modifying anything.

investigate before executing

auto

Route actions through the auto-mode classifier. Ignored in project/local settings — set it in user settings only.

~/.claude/settings.json only

bypassPermissions

Skip all permission prompts. Dangerous. Can be blocked with disableBypassPermissionsMode: "disable".

--dangerously-skip-permissions

Permission rules

permissions.allow / ask / deny hold rules in the form Tool or Tool(specifier). Rules evaluate deny → ask → allow, and the FIRST match wins regardless of specificity.

allow

Permit the matching tool use without prompting.

["Bash(git diff *)"]

ask

Prompt for confirmation on the matching tool use.

["Bash(git push *)"]

deny

Block the tool use — also used to hide sensitive files from Claude.

["Read(./.env)", "Bash(curl *)"]

additionalDirectories

Extra working directories Claude may access.

["../docs/"]

Bash(npm run *)

Matches Bash commands starting with npm run.

prefix wildcard

Read(./.env)

Matches reading the project .env file.

path specifier

WebFetch(domain:example.com)

Matches fetch requests to example.com.

domain specifier

"*" / "mcp__*"

In deny, * blocks every tool and mcp__* blocks all MCP tools.

broad lockdown

Key settings reference

A curated slice of settings.json — the keys most worth knowing. The full list lives in the official docs.

Model & core behavior

model

Override the default model. --model / ANTHROPIC_MODEL override it for one session.

"claude-sonnet-5"

fallbackModel

Ordered fallback chain when the primary model is overloaded (max 3).

["claude-sonnet-5", "claude-haiku-4-5"]

env

Environment variables applied to every session and to subprocesses Claude spawns.

{"CLAUDE_CODE_ENABLE_TELEMETRY": "1"}

apiKeyHelper

Shell command that generates an auth value, sent as X-Api-Key / Authorization: Bearer.

/bin/generate_temp_api_key.sh

outputStyle

Select an output style that adjusts the system prompt. Applies on restart / /clear.

"Explanatory"

cleanupPeriodDays

Days to retain session files (default 30, min 1). 0 is rejected.

20

autoCompactEnabled

Auto-compact the conversation near the context limit (default true).

false

Hooks, status line & attribution

hooks

Custom commands run at lifecycle events (PreToolUse, PostToolUse, etc.).

see hooks docs

disableAllHooks

Disable all hooks and any custom status line.

true

statusLine

Command-driven custom status line.

{"type": "command", "command": "~/.claude/statusline.sh"}

attribution

Customize git commit / PR attribution. Supersedes the deprecated includeCoAuthoredBy. Empty strings hide it.

{"commit": "...", "pr": ""}

includeCoAuthoredBy

Deprecated toggle for the Co-Authored-By trailer — use attribution instead.

false

MCP servers

enableAllProjectMcpServers

Automatically approve every MCP server defined in project .mcp.json files.

true

enabledMcpjsonServers

Approve specific .mcp.json servers by name.

["memory", "github"]

disabledMcpjsonServers

Reject specific .mcp.json servers by name.

["filesystem"]

Authentication & enterprise

forceLoginMethod

Restrict login: claudeai, console, or gateway.

"claudeai"

forceLoginOrgUUID

Require login to a specific Anthropic organization (UUID, or array of UUIDs).

"xxxxxxxx-…"

awsAuthRefresh

Script that refreshes the .aws directory (interactive SSO).

aws sso login --profile myprofile

awsCredentialExport

Script that outputs JSON AWS credentials (non-interactive).

/bin/generate_aws_grant.sh

Sandboxing

Bash sandboxing isolates commands from the filesystem and network (macOS / Linux / WSL2).

sandbox.enabled

Turn on bash sandboxing (default false).

true

sandbox.filesystem.allowWrite / denyRead

Extra writable paths / blocked read paths. Merge across scopes and with Edit/Read rules.

["/tmp/build"] · ["~/.aws/credentials"]

sandbox.network.allowedDomains / deniedDomains

Outbound domain allow / deny lists (wildcards supported; deny wins).

["github.com", "*.npmjs.org"]

Plugins

enabledPlugins

Enable/disable plugins by plugin-name@marketplace.

{"formatter@acme-tools": true}

extraKnownMarketplaces

Additional plugin marketplaces available to the repo.

{"acme-tools": {"source": {…}}}

strictKnownMarketplaces

Managed only. Allowlist of marketplace sources (empty array = lockdown).

[{"source": "github", "repo": "acme/plugins"}]

Verify & diagnose

/config

Open the tabbed Settings UI, or set one option inline with key=value (v2.1.181+).

/config verbose=true

/status

Shows which setting sources are active (User / Project / managed channel).

Setting sources line

/doctor

Lists each invalid entry with its source and field when a file fails validation.

diagnose errors

/model

Switch model mid-session (since model is read at start).

live model change

Key takeaways

Precedence (high → low): Managed → CLI args → Local → Project → User. Managed policy can't be overridden by anything.
Scalars override; arrays merge. Permission rules and sandbox path lists concatenate across scopes and de-duplicate.
Put team-shared config in .claude/settings.json (committed); keep personal per-repo tweaks in .claude/settings.local.json (gitignored).
Hide secrets with permissions.deny Read(...) rules — this replaces the deprecated ignorePatterns.
permissions.defaultMode values: default/manual, acceptEdits, plan, auto (user-scope only), bypassPermissions.
Permission rules evaluate deny → ask → allow, first match wins — order matters, not specificity.
Use attribution (not the deprecated includeCoAuthoredBy) to customize or hide commit/PR credit.

Summarized from the official Claude Code settings documentation (code.claude.com/docs/en/settings) for study. Always check the live docs for the newest keys and defaults.

← Back to the Study Guide

KEEP EXPLORINGBrowse the full study guide ↗Review the certification cheat sheet ↗Try a Claude practice exam ↗

OFFICIAL REFERENCEClaude Code settings documentation ↗

Independent study notes. Consult the official documentation for current product behavior and exam requirements.

About this guide & our sources ↗