Detailed Analysis
Anthropic's Claude Code SDK exposes the same filesystem-based infrastructure that powers the Claude Code CLI, giving developers building agent applications access to a mature, layered configuration system without requiring custom tooling. The core mechanism for controlling this system is the `settingSources` option — called `setting_sources` in Python and `settingSources` in TypeScript — which governs which filesystem-based settings the SDK loads at session initialization. Developers can select from three discrete source levels: `"project"` (loading CLAUDE.md files, rules, project skills, hooks, and settings from the working directory and its parents), `"user"` (loading equivalent configurations from the user's home directory), and `"local"` (loading gitignored overrides from the working directory). Omitting the option entirely defaults to loading all three sources, matching the behavior of the interactive CLI. Crucially, certain inputs — managed policy settings, the global `~/.claude.json` configuration, and auto-memory — are always loaded regardless of how `settingSources` is configured, establishing a clear separation between developer-controlled settings and platform-level governance.
The CLAUDE.md system represents one of the more architecturally significant features exposed through the SDK. These markdown files provide agents with persistent contextual grounding — coding conventions, architecture decisions, build commands — that is injected into the agent's context at session start rather than repeated in individual prompts. The loading hierarchy is additive across multiple levels: project-root files, parent-directory files, child-directory files (loaded on demand as the agent traverses subdirectories), local gitignored overrides, and user-level files all coexist without automatic precedence rules. This design places the burden of conflict resolution on the developer, who is explicitly advised to include precedence declarations in more specific files. The flexibility of the hierarchy enables sophisticated multi-project setups where user-level preferences can coexist with project-specific overrides, but it equally creates surfaces for unintended instruction conflicts if documentation discipline is not maintained.
Skills and hooks complete the extensibility picture, each serving distinct roles within agent workflows. Skills are markdown files that provide specialized knowledge and invocable workflows, but unlike CLAUDE.md files, they are loaded on demand rather than at session start — the agent receives only descriptions at startup and fetches full content when relevance is determined. This lazy-loading design constrains context consumption and allows agents to maintain broad capability libraries without incurring upfront token costs. Hooks, meanwhile, operate as execution-control mechanisms with two parallel delivery modes: filesystem hooks defined in `settings.json` (which run when the corresponding `settingSources` is active) and programmatic hooks passed directly as callback functions to `query()`. The programmatic variant is particularly notable because it runs within the application process itself and returns structured decision objects, enabling developers to implement real-time tool-use gating logic — such as blocking or approving specific tool calls — through native application code rather than shell-level scripting.
The broader significance of this documentation lies in what it reveals about Anthropic's architectural strategy for Claude Code as a platform. By unifying the SDK and CLI on the same underlying filesystem infrastructure, Anthropic reduces the cognitive and operational gap between interactive developer usage and production agent deployment. A team that configures CLAUDE.md files and hooks for their own Claude Code CLI sessions can move those configurations directly into SDK-powered automated workflows without translation or duplication. This continuity lowers the barrier to deploying persistent, context-aware agents in codebases where project-level conventions are already documented. It also signals that Anthropic views the filesystem as a durable, first-class configuration surface — one that integrates naturally with version control and developer tooling — rather than treating programmatic configuration as the exclusive path for serious production use.
Read original article →