Settings

Analyzed: March 31, 2026 leak snapshot

​

Settings sources and precedence

src/utils/settings/constants.ts defines five settings sources:

• userSettings
• projectSettings
• localSettings
• flagSettings
• policySettings

The file comment is explicit: later sources override earlier ones. That means policy settings sit at the highest precedence in the merge order shown in source.

​

What the settings system does

The settings layer under src/utils/settings/ is responsible for:

• finding the right settings files
• parsing JSON safely
• validating against the schema
• preserving backward compatibility
• caching parsed results
• merging sources
• watching files for changes

This is a real configuration subsystem, not a thin JSON loader.

​

Schema strategy

src/utils/settings/types.ts contains a large Zod schema with explicit backward-compatibility notes. The code comments define allowed evolution patterns:

• add optional fields
• add enum values
• add properties
• make validation more permissive

And it explicitly warns against:

• removing fields
• removing enum values
• making optional fields required
• making types more restrictive

That is one of the clearest signs that Claude Code treats settings files as a stable public interface.

​

What settings cover

The schema includes, among other things:

• environment variables
• permissions
• hooks
• marketplaces and plugins
• MCP-related controls
• customization surfaces like skills and agents
• memory and automation-related options

The settings file is therefore not just UI preferences. It is one of the main policy-control planes for the product.

​

Validation behavior

Validation lives in src/utils/settings/validation.ts. The important behavior is pragmatic rather than purist:

• malformed files are reported, not blindly trusted
• invalid permission rules are filtered so one bad rule does not poison the whole file
• validation errors are formatted into human-readable messages
• unknown or invalid content can remain on disk even if it is ignored at runtime

This matches the backward-compatibility stance in the schema comments.

​

Managed and drop-in settings

src/utils/settings/settings.ts supports managed settings through:

• a base managed-settings.json
• a managed-settings.d/ drop-in directory

The load order is:

1. base managed file
2. alphabetically sorted drop-ins layered on top

That is a familiar admin model borrowed from system configuration conventions, and it allows multiple policy fragments to coexist without editing one shared file.

​

Root path and source scoping

The settings subsystem also tracks each source’s root path. That matters for features such as:

• relative path interpretation
• project-root scoping
• trusted versus untrusted settings sources

For example, the memory-path code intentionally excludes some project-committed settings sources for security reasons.

​

File watching and change detection

The source includes a change-detector layer so settings updates can propagate without restart. This is why features like permissions, plugins, and policy settings can react to config edits during a session rather than only at startup.

​

Relationship to older config

src/utils/config.ts still carries older global and project config structures. So the repo has two overlapping configuration worlds:

• modern settings via src/utils/settings/*
• legacy and operational config via src/utils/config.ts

They are related but not identical. Settings are the structured, schema-validated control plane. Config also carries app metadata, session stats, onboarding state, and project bookkeeping.

​

Practical reading of precedence

The effective runtime configuration is not “whatever is in settings.json.” It is:

1. each source parsed independently
2. invalid parts filtered or rejected
3. cached
4. merged in precedence order
5. consumed by the relevant subsystems

If behavior looks surprising, precedence and source enablement are the first things to check.

​

Related links

• MCP
• State & persistence
• Memory System
• Commands Overview