Mental Model

Claude Code's configuration system has five scopes, three permission types, six permission modes, and over 100 environment variables. This page maps the entire system so you know exactly what controls what.

The Five Scopes

Every setting in Claude Code belongs to one of five scopes. Settings merge from lowest to highest priority, with more specific scopes overriding broader ones.

Managed (highest priority)
  ↓
CLI arguments
  ↓
Local (.claude/settings.local.json)
  ↓
Project (.claude/settings.json)
  ↓
User (~/.claude/settings.json) (lowest priority)

Array merge behavior: Array-valued settings like permissions.allow are concatenated and deduplicated across scopes, not replaced. Lower-priority scopes add entries without overriding higher-priority ones.

Managed tier precedence: Within the managed tier, the order is: server-managed > MDM/OS-level policies > file-based (managed-settings.d/*.json + managed-settings.json) > HKCU registry (Windows only). Only one managed source is used — sources do not merge across tiers.

Managed Settings Delivery

Managed settings reach machines through multiple channels:

• Server-managed: Anthropic's servers via Claude.ai admin console
• macOS MDM: com.anthropic.claudecode managed preferences domain (Jamf, Kandji)
• Windows Group Policy: HKLM\SOFTWARE\Policies\ClaudeCode registry key
• Windows user-level: HKCU\SOFTWARE\Policies\ClaudeCode (lowest policy priority)
• File-based: Platform-specific paths with a drop-in directory

File-based paths:

The drop-in directory managed-settings.d/ sits alongside the main file. Files are sorted alphabetically and deep-merged. Use numeric prefixes (10-telemetry.json, 20-security.json) to control merge order.

# Example: managed-settings.d/ drop-in directory
/etc/claude-code/
  managed-settings.json              # Base managed config
  managed-settings.d/
    10-telemetry.json                # {"disableTelemetry": true}
    20-security.json                 # {"permissions": {"deny": [...]}}
    30-models.json                   # {"availableModels": ["sonnet"]}

// 20-security.json — merged into managed-settings.json
{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ]
  },
  "allowManagedPermissionRulesOnly": true
}

Permission System Architecture

Three Rule Types

Evaluation order: deny → ask → allow. First match wins. Deny always takes precedence over everything.

Six Permission Modes

Set via permissions.defaultMode in settings or --permission-mode at startup.

Permission Rule Syntax

Rules follow the format Tool or Tool(specifier).

Bash patterns:

Bash                          # Matches ALL Bash commands
Bash(npm run build)           # Exact match
Bash(npm run *)               # Glob wildcard (space = word boundary)
Bash(npm*)                    # No space = no word boundary; matches "npm" and "npmrc"
Bash(git * main)              # Wildcard in middle
Bash(* --version)             # Wildcard at start

Read/Edit patterns (gitignore syntax):

Read(./.env)                  # Relative to current directory
Read(/src/**/*.ts)            # Relative to project root
Read(~/Documents/*.pdf)       # Home directory
Read(//Users/alice/secrets)   # Absolute path (double slash!)
Edit(/docs/**)                # Recursive in project docs/

Other tools:

WebFetch(domain:example.com)  # Domain restriction
mcp__puppeteer                # All tools from an MCP server
mcp__puppeteer__navigate      # Specific MCP tool
Agent(Explore)                # Specific subagent

Compound Command Awareness

Claude Code is shell-aware. Bash(safe-cmd *) does NOT allow safe-cmd && dangerous-cmd. Shell operators (&&, ||, ;, |, |&, &, newlines) are recognized and each subcommand must match independently.

Process wrappers: Before matching, Claude Code strips timeout, time, nice, nohup, stdbuf, and bare xargs. So Bash(npm test *) also matches timeout 30 npm test.

Managed-Only Settings

These settings have NO effect in user or project settings — they only work in managed settings:

Placing these in project or user settings does nothing — no error, no warning, just silent ignore.

Model Selection Strategy

Available Models and Aliases

Model Priority Order

1. /model <alias> during session (highest)
2. claude --model <alias> at startup
3. ANTHROPIC_MODEL environment variable
4. model field in settings.json (lowest)

Effort Levels

Controls adaptive reasoning depth. Supported on Opus 4.6 and Sonnet 4.6.

Set via /effort, --effort flag, CLAUDE_CODE_EFFORT_LEVEL env var, or effortLevel in settings. Include "ultrathink" in a prompt to trigger high effort for a single turn.

Cost Guidance

Opus 4.6 is roughly 15x more expensive than Haiku. Pick models deliberately:

The Profile System

Claude Code has no built-in profile system. Profiles are achieved through CLAUDE_CONFIG_DIR, which points to a fully isolated configuration directory — credentials, settings, history, plugins, agents, hooks.

# Create profile directories
mkdir -p ~/.claude-work ~/.claude-personal
 
# Shell aliases
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'
alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'

Each profile directory is completely independent. Switching profiles means switching everything.

Community tools for profile management:

• claude-code-profiles: Complete isolated profile directories
• claudectx: claudectx work switches in one command
• claude-provider: Plugin + CLI for switching providers

Key Environment Variables

Over 100 environment variables exist. These are the ones that matter most:

All env vars can also be set in settings.json under the env key, making them version-controllable.

The settings.json Schema

Add the official JSON Schema for IDE autocomplete:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

This gives you validation and autocomplete for every field in your editor. The schema covers all settings.json fields including permissions, hooks, sandbox, model, env, and the 50+ other configuration options.