Lesson 16 — Settings & Configuration

The 5-layer cascade, SettingsSchema, change detection, MDM, and remote managed settings

1. Overview: why a cascade?

Claude Code runs in radically different contexts: a solo developer's laptop, a shared team repository, a CI agent, and an enterprise fleet managed by an IT department. A single flat config file cannot serve all of these at once.

The solution is a priority cascade: five independently-writable sources are merged in order, lower-to-higher priority. Each layer can add to or override anything below it. The result is a single merged SettingsJson object the rest of the codebase reads.

2. The 5-layer cascade

The canonical source of truth is constants.ts, which defines the SETTING_SOURCES array in merge order:

export const SETTING_SOURCES = [
  'userSettings',    // lowest priority
  'projectSettings',
  'localSettings',
  'flagSettings',
  'policySettings',  // highest priority
] as const

Later entries override earlier ones. The merge happens in loadSettingsFromDisk() via lodash mergeWith with a custom array-deduplication strategy.

Priority stack — low to high

Cascade flow diagram

// settings.ts — simplified for clarity
function loadSettingsFromDisk(): SettingsWithErrors {
  let mergedSettings: SettingsJson = {}

  // Plugin settings are the lowest-priority base layer
  const pluginSettings = getPluginSettingsBase()
  if (pluginSettings) {
    mergedSettings = mergeWith(mergedSettings, pluginSettings, settingsMergeCustomizer)
  }

  for (const source of getEnabledSettingSources()) {
    if (source === 'policySettings') {
      // First-source-wins among: remote → MDM → file → HKCU
      const policySettings = resolvePolicySettings()
      if (policySettings) {
        mergedSettings = mergeWith(mergedSettings, policySettings, settingsMergeCustomizer)
      }
      continue
    }

    const { settings } = parseSettingsFile(getSettingsFilePathForSource(source))
    if (settings) {
      mergedSettings = mergeWith(mergedSettings, settings, settingsMergeCustomizer)
    }
  }

  return { settings: mergedSettings, errors: allErrors }
}

3. SettingsSchema: what can be configured

SettingsSchema in types.ts is a Zod v4 schema that defines every valid key. It is used to validate every settings source before merging. Invalid files surface ValidationError[] but do not crash Claude Code — the rest of the valid configuration still loads.

Top-level keys (selected)

Example settings file

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

  "model": "claude-opus-4-5",

  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  },

  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(git *)", "Read(**)"],
    "deny":  ["Bash(rm -rf *)"]
  },

  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "echo pre-bash" }]
    }]
  },

  "cleanupPeriodDays": 7
}

4. Merge semantics

Claude Code uses lodash mergeWith throughout the settings pipeline, with a custom settingsMergeCustomizer:

// settings.ts
export function settingsMergeCustomizer(
  objValue: unknown,
  srcValue: unknown,
): unknown {
  if (Array.isArray(objValue) && Array.isArray(srcValue)) {
    return uniq([...objValue, ...srcValue])  // deduplicated concatenation
  }
  return undefined  // let lodash handle objects / scalars
}

5. The 3-tier cache

Claude Code reads settings files synchronously on the critical startup path. Three caching layers prevent redundant disk I/O and Zod re-parsing:

All three caches are cleared atomically by resetSettingsCache(). This single call is the "fan-out" step in the change detector: one cache reset means one disk reload regardless of how many React components or hooks are subscribed.

6. Change detection

Settings files can change while Claude Code is running. The settingsChangeDetector (in changeDetector.ts) watches files with chokidar and polls MDM registries/plists every 30 minutes.

File watching architecture

Key constants

const FILE_STABILITY_THRESHOLD_MS = 1000   // wait for write to stabilize
const FILE_STABILITY_POLL_INTERVAL_MS = 500  // chokidar awaitWriteFinish
const INTERNAL_WRITE_WINDOW_MS = 5000        // suppress own writes
const MDM_POLL_INTERVAL_MS = 30 * 60 * 1000  // 30 min MDM registry poll
const DELETION_GRACE_MS = 1700              // absorb delete-and-recreate

// updateSettingsForSource() before file write:
markInternalWrite(filePath)
writeFileSyncAndFlush_DEPRECATED(filePath, jsonStringify(updatedSettings, null, 2))
resetSettingsCache()

function fanOut(source: SettingSource): void {
  resetSettingsCache()        // one clear
  settingsChanged.emit(source)  // N subscribers; first one pays the disk miss
                                // subsequent ones hit the repopulated cache
}

7. MDM & file-based managed settings

The policySettings layer has four internal sub-sources. The first one that has non-empty content wins — the others are ignored for this session.

Policy sub-source priority

Platform paths for managed-settings.json

Drop-in directory merge order

The managed-settings.d/ directory enables multiple teams to deliver independent policy fragments without editing a single shared file. Files are sorted alphabetically and merged in order — later files override earlier ones. This follows the systemd/sudoers convention.

// settings.ts — loadManagedFileSettings()
// 1. Load managed-settings.json as base (lowest precedence)
const { settings } = parseSettingsFile(getManagedSettingsFilePath())

// 2. Load and sort drop-in files
const entries = fs.readdirSync(dropInDir)
  .filter(d => d.isFile() && d.name.endsWith('.json'))
  .map(d => d.name)
  .sort()  // alphabetical: 10-otel.json, 20-security.json …

for (const name of entries) {
  merged = mergeWith(merged, parseSettingsFile(join(dropInDir, name)).settings, ...)
}

MDM raw read — startup parallelism

Reading the macOS plist (plutil -convert json) and Windows registry (reg query) requires spawning subprocesses. These are fired as early as possible during startup (before module initialization completes) so the subprocess runs in parallel with module loading. By the time ensureMdmSettingsLoaded() is awaited, the result is typically already available.

// mdm/settings.ts
export function startMdmSettingsLoad(): void {
  mdmLoadPromise = (async () => {
    const rawPromise = getMdmRawReadPromise() ?? fireRawRead()
    const { mdm, hkcu } = consumeRawReadResult(await rawPromise)
    mdmCache = mdm
    hkcuCache = hkcu
  })()
}

8. Remote managed settings

For Enterprise/Team subscribers and all Console (API key) users, Claude Code fetches settings from the Anthropic API at startup. This is the highest-priority sub-source within policySettings.

Eligibility

Fetch lifecycle

ETag-based caching (checksum)

To avoid re-downloading unchanged settings on every startup, Claude Code computes a SHA-256 checksum of the cached settings and sends it as an If-None-Match header. The server returns 304 Not Modified if nothing changed. The checksum algorithm matches the server's Python implementation exactly:

// Must match Python: json.dumps(settings, sort_keys=True, separators=(",", ":"))
export function computeChecksumFromSettings(settings: SettingsJson): string {
  const sorted = sortKeysDeep(settings)       // recursive key sort
  const normalized = jsonStringify(sorted)    // no spaces after separators
  const hash = createHash('sha256').update(normalized).digest('hex')
  return `sha256:${hash}`
}

Fail-open design

Security check for dangerous changes

When remote settings arrive with content that differs from the cache, checkManagedSettingsSecurity() runs before applying them. If the incoming settings are considered dangerous (e.g., new hooks, changed permission rules), the user is prompted to approve. Rejecting leaves the previous cached settings in place.

9. Settings sync (CCR)

Settings sync (services/settingsSync/) is a separate mechanism from remote managed settings. It syncs a user's own settings across environments — primarily between the interactive CLI and Claude Code in Repositories (CCR) headless mode.

Sync keys

export const SYNC_KEYS = {
  USER_SETTINGS:  '~/.claude/settings.json',
  USER_MEMORY:    '~/.claude/CLAUDE.md',
  projectSettings: (projectId: string) =>
    `projects/${projectId}/.claude/settings.local.json`,
  projectMemory:  (projectId: string) =>
    `projects/${projectId}/CLAUDE.local.md`,
}

The project-specific keys are scoped by a SHA of the git remote URL, so settings for github.com/org/repo-A never overwrite settings for github.com/org/repo-B.

10. Security constraints

Several settings keys intentionally exclude projectSettings from their trust domain. A malicious repo could otherwise inject dangerous settings automatically.

11. Key Takeaways

• Settings are merged from 5 layers in order: user → project → local → flag → policy. Later layers override earlier ones. Arrays are deduplicated-concatenated across layers.
• policySettings uses first-source-wins internally: remote beats MDM (plist/HKLM) beats managed-settings.json beats HKCU. Only the first non-empty source is applied.
• The 3-tier cache (session, per-source, per-file) keeps startup fast. A single resetSettingsCache() invalidates all three and is called atomically before notifying subscribers.
• Change detection uses chokidar file watching for user/project/local/policy files plus a 30-minute MDM poll. Internal writes are suppressed with a 5-second window to prevent reload loops.
• Remote managed settings are the highest-priority policy sub-source, fetched at startup with ETag caching, retried up to 5 times, and polled hourly. The system always fails open — a failed fetch falls back to the cached file or simply skips remote settings.
• Settings sync is orthogonal to remote managed settings. It syncs the user's own settings files (not enterprise policy) between CLI and CCR using a cloud key-value store, scoped by git remote hash.
• Several security-sensitive flags (skipDangerousModePermissionPrompt, auto-mode opt-in, classifier rules) intentionally exclude projectSettings to prevent malicious repositories from escalating their own privileges.
• The backward-compatibility contract in SettingsSchema forbids removing fields or enum values. New fields must be optional. Invalid individual permission rules are stripped before Zod validation so one bad rule cannot null out the entire settings file.