From 6638b86cb7a66186f9bca5ea4bc0301ff3bf4a93 Mon Sep 17 00:00:00 2001 From: Tejas Amle Date: Mon, 13 Jul 2026 05:33:24 +0000 Subject: [PATCH] docs(readme): document filesystem settings defaults and CLAUDE.md loading The README never states that the SDK loads user/project/local filesystem settings (including CLAUDE.md, slash commands, and subagents) by default, matching CLI behavior. Users hit this in both directions: expecting memory to load when it does not appear to, and being surprised that deployed agents inherit host-machine settings. Add a short subsection stating the default, the production implication, and two copy-pasteable setting_sources examples. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01BtNuvm15JHJv7c6QV28gsh --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 8d8445238..87869d032 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,25 @@ options = ClaudeAgentOptions( ) ``` +### Filesystem Settings and CLAUDE.md + +By default, the SDK loads filesystem settings the same way the CLI does: the user (`~/.claude`), project (`.claude/` in the working directory), and local (`.claude/settings.local.json`) sources are all read — including `CLAUDE.md` memory files, custom slash commands, and subagents. Your project's `CLAUDE.md` is picked up automatically; no extra configuration is needed. + +The flip side is that a deployed agent inherits whatever settings exist on its host machine, so behavior can differ between your laptop and CI, Docker, or Kubernetes. Use `setting_sources` to make this explicit: + +```python +# Hermetic (recommended for production/CI): ignore all filesystem settings +options = ClaudeAgentOptions(setting_sources=[]) + +# Load only project settings and CLAUDE.md — nothing user- or machine-specific +options = ClaudeAgentOptions( + cwd="/path/to/project", + setting_sources=["project"], +) +``` + +When passing an explicit list, include `"project"` if you want `CLAUDE.md` loaded. See the `setting_sources` docstring in [src/claude_agent_sdk/types.py](src/claude_agent_sdk/types.py) for details. + ## ClaudeSDKClient `ClaudeSDKClient` supports bidirectional, interactive conversations with Claude