[
    {
        "role": "user",
        "content": "when%20using%20claude%20agent%20sdk%20in%20python%2C%20are%20the%20usual%20claude%20code%20cli%20rules%20for%20loading%20%7E%2F.claude%2C%20CLAUDE.md%2C%20and%20history%20done%20same%20as%20cli%20or%20must%20be%20done%20manually%3F"
    },
    {
        "role": "assistant",
        "content": "When using the Claude Agent SDK in Python, certain filesystem-based configuration sources like `~/.claude/CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.md`, as well as `.claude/settings.json`, `.claude/commands/` etc., *are not loaded by default*. They *can* be loaded, but you must explicitly configure the SDK to do so. The behavior is not identical to the CLI (or default Claude Code), where these are often auto-loaded. Below is a more detailed breakdown.\n\n---\n\n### What these files are\n\n- **CLAUDE.md** (or `.claude/CLAUDE.md`) \u2014 project- or user-level instructions / memory, used by Claude Code / CLI to provide context when operating inside project directories. ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/sdk/sdk-overview?utm_source=openai))  \n- `.claude/settings.json` (and optionally `.claude/settings.local.json` or `~/.claude/settings.json`) \u2014 configuration files, for skills, hooks, commands, tools, etc. ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/python?utm_source=openai))  \n\n---\n\n### Python SDK defaults vs CLI\n\n#### Defaults\n\n- By default, **without any special options**, the Python SDK **does *not*** load any of the filesystem settings sources. That means CLAUDE.md, project- or user-level `.settings.json`, commands, skills, etc. will *not* be included. ([platform.claude.com](https://platform.claude.com/docs/en/agent-sdk/python?utm_source=openai))  \n- Also, `setting_sources` defaults to `None`, meaning \u201cno loading from disk.\u201d ([code.claude.com](https://code.claude.com/docs/en/agent-sdk/python?utm_source=openai))  \n\nThis is different from the CLI / \u201cClaude Code frontend,\u201d which tends to pick up settings and CLAUDE.md automatically when you're inside a project tree. \n\n#### Explicitly loading these in Python SDK\n\nTo get behavior similar to the CLI\u2014i.e. load CLAUDE.md, project settings, etc.\u2014you must provide the appropriate `setting_sources` in `ClaudeAgentOptions`. For example:\n\n```python\nfrom claude_agent_sdk import query, ClaudeAgentOptions\n\nasync for message in query(\n    prompt=\"Add a new feature following project conventions\",\n    options=ClaudeAgentOptions(\n        system_prompt={\"type\": \"preset\", \"preset\": \"claude_code\"},\n        setting_sources=[\"project\"],\n        allowed_tools=[\"Read\", \"Write\", \"Edit\"]\n    ),\n):\n    print(message)\n```\n\nHere, `setting_sources=[\"project\"]` tells it to load project\u2010level settings, which includes `.claude/settings.json` and `CLAUDE.md` in that project. ([platform.claude.com](https://platform.claude.com/docs/en/agent-sdk/python?utm_source=openai))  \n\nIf you want to include user settings (`~/.claude`) or local settings (`.claude/settings.local.json`), you can set `setting_sources` to include `\"user\"` or `\"local\"` too. ([platform.claude.com](https://platform.claude.com/docs/en/agent-sdk/python?utm_source=openai))  \n\n---\n\n### On \u201chistory\u201d / conversation context\n\n- When you use the Python SDK with methods like `query()` without specifying a session or using `ClaudeSDKClient`, you **do not** get persistence of conversation history in the way the CLI might (unless you use a session via `ClaudeSDKClient`). The SDK doesn\u2019t auto-load earlier messages from prior runs unless those were stored by your application.  \n- The concept of \u201cresume\u201d exists: you can resume a conversation session by supplying a `session_id` or setting `resume=` in `ClaudeAgentOptions`. But this is different from loading filesystem config files; it's about continuing context. ([docs.claude.com](https://docs.claude.com/en/docs/agent-sdk/python?utm_source=openai))  \n\n---\n\n### Summary table\n\n| Feature                          | CLI / Claude Code (Default)                            | Python SDK (Default)                                    | How to enable in Python SDK                            |\n|----------------------------------|----------------------------------------------------------|----------------------------------------------------------|---------------------------------------------------------|\n| Load user/project/local settings | \u2705                                                       | \u274c (default)                                             | Use `setting_sources` including `\"user\"`, `\"project\"`, `\"local\"` ([platform.claude.com](https://platform.claude.com/docs/en/agent-sdk/python?utm_source=openai)) |\n| Load CLAUDE.md for project/user  | \u2705                                                       | \u274c (unless `setting_sources` includes `\"project\"` or `\"user\"`) | Include `\"project\"` (or `\"user\"`) in `setting_sources` ([docs.claude.com](https://docs.claude.com/en/docs/claude-code/sdk/sdk-overview?utm_source=openai)) |\n| Conversation history persistence | Yes, via sessions / CLI state                            | Only within same process/session; SDK must be told to resume or use client object | Use `ClaudeSDKClient` and optional `resume` or reuse session object ([docs.claude.com](https://docs.claude.com/en/docs/agent-sdk/python?utm_source=openai)) |\n\n---\n\n### Practical recommendation\n\nIf you want your Python SDK agent to behave like the CLI in terms of loading `CLAUDE.md`, project rules, settings, etc., do this:\n\n1. Set `setting_sources` in your `ClaudeAgentOptions` to include the relevant sources (probably `\"project\"`, possibly `\"user\"`).  \n2. Use `system_prompt={\"type\": \"preset\", \"preset\": \"claude_code\"}` or manually load text from a CLAUDE.md file into your system prompt if needed.  \n3. If you want to maintain conversation over multiple turns (history), use `ClaudeSDKClient` rather than repeated `query()` calls, or use `resume=` to continue sessions stored by some mechanism.  \n\n---\n\n### Bottom line\n\nNo \u2014 by default, the usual CLI / Claude Code rules for loading `~/.claude/CLAUDE.md`, project-level `CLAUDE.md`, history, etc., are *not* automatically done in the Python SDK. They are *optional*, and you must configure them explicitly via `setting_sources`, session options, etc. If you want the SDK to behave like the CLI in this regard, set those options.  \n\nIf you like, I can show you a minimal code sample that ensures the SDK reads your `CLAUDE.md` (both project and user) and preserves history across calls. Do you want that?"
    }
]