diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index 7469824..ae9864f 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -311,3 +311,6 @@ tags: [daily] - 13:21 (<1min) | `memory-compiler` - **Asked:** Create and file a structured wiki article on the TypeScript V2 SDK interface into the knowledge base. - **Done:** Wrote article covering V2 exports and usage patterns, then updated both the agent-sdk topic index and master index with new counts. +- 13:22 (<1min) | `memory-compiler` + - **Asked:** Compile a new wiki article on Claude Code features into the knowledge base with updated indexes. + - **Done:** Added structured article on Claude Code SDK features and updated both index files to reflect 29 total articles. diff --git a/raw/Use Claude Code features in the SDK.md b/raw/_processed/Use Claude Code features in the SDK.md similarity index 100% rename from raw/Use Claude Code features in the SDK.md rename to raw/_processed/Use Claude Code features in the SDK.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index a3c40a0..05dc798 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -30,7 +30,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 19 | -| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 28 | +| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 29 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | | [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 12 | diff --git a/wiki/agent-sdk/_index.md b/wiki/agent-sdk/_index.md index 298597a..73394e9 100644 --- a/wiki/agent-sdk/_index.md +++ b/wiki/agent-sdk/_index.md @@ -42,3 +42,4 @@ Build production AI agents using the same tools, agent loop, and context managem | [[wiki/agent-sdk/todo-tracking\|todo-tracking]] | Built-in TodoWrite tool: lifecycle states, automatic triggers, real-time progress display, activeForm field | raw/Todo Lists.md | 2026-04-17 | | [[wiki/agent-sdk/cost-tracking\|cost-tracking]] | Token usage tracking, deduplicating parallel tool calls, per-model cost breakdown, accumulating across sessions | raw/Track cost and usage.md | 2026-04-17 | | [[wiki/agent-sdk/typescript-v2-interface\|typescript-v2-interface]] | V2 preview: session-based send/stream pattern, no async generators, createSession/resumeSession/prompt, cleanup | raw/TypeScript SDK V2 interface (preview).md | 2026-04-17 | +| [[wiki/agent-sdk/claude-code-features-in-sdk\|claude-code-features-in-sdk]] | settingSources control, CLAUDE.md loading, skills discovery, filesystem vs programmatic hooks, multi-tenant isolation | raw/Use Claude Code features in the SDK.md | 2026-04-17 | diff --git a/wiki/agent-sdk/claude-code-features-in-sdk.md b/wiki/agent-sdk/claude-code-features-in-sdk.md new file mode 100644 index 0000000..2fbabac --- /dev/null +++ b/wiki/agent-sdk/claude-code-features-in-sdk.md @@ -0,0 +1,128 @@ +--- +title: "Use Claude Code Features in the SDK" +aliases: [setting-sources, sdk-claude-md, sdk-skills-hooks] +tags: [agent-sdk, settings, skills, hooks, claude-md, configuration] +sources: [raw/Use Claude Code features in the SDK.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Use Claude Code Features in the SDK + +SDK agents share the same filesystem-based feature layer as the Claude Code CLI: `CLAUDE.md` instructions, skills, hooks, and settings. The `settingSources` option controls which of these load. + +## settingSources + +Controls which filesystem locations the SDK reads at startup. + +| Source | Loads from | Contents | +|--------|-----------|----------| +| `"project"` | `/.claude/` and parent dirs | CLAUDE.md, `.claude/rules/*.md`, project skills, project hooks, `settings.json` | +| `"user"` | `~/.claude/` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | +| `"local"` | `/` | `CLAUDE.local.md` (gitignored), `settings.local.json` | + +- Omitting `settingSources` → equivalent to `["user", "project", "local"]` +- Pass `settingSources: []` to disable all three (programmatic-only mode) + +```python +options=ClaudeAgentOptions( + setting_sources=["user", "project"], + allowed_tools=["Read", "Edit", "Bash"], +) +``` + +### What settingSources does NOT control + +These load regardless: + +| Input | To disable | +|-------|-----------| +| Managed policy settings | Remove the managed settings file | +| `~/.claude.json` global config | Relocate with `CLAUDE_CONFIG_DIR` in `env` | +| Auto memory (`~/.claude/projects//memory/`) | `autoMemoryEnabled: false` or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` | + +**Multi-tenant isolation:** use separate filesystems per tenant + `settingSources: []` + `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`. See [[wiki/agent-sdk/secure-deployment|secure-deployment]]. + +## Project Instructions (CLAUDE.md and rules) + +- Loaded when `settingSources` includes `"project"` +- All levels are **additive** — project + user CLAUDE.md both load, no hard precedence +- Child-dir `CLAUDE.md` files load on demand when agent reads a file in that subtree + +| Level | Location | +|-------|---------| +| Project root | `/CLAUDE.md` or `/.claude/CLAUDE.md` | +| Project rules | `/.claude/rules/*.md` | +| Parent dirs | CLAUDE.md in any ancestor of `cwd` | +| Child dirs | CLAUDE.md in subdirs (loaded on demand) | +| Local (gitignored) | `/CLAUDE.local.md` | +| User | `~/.claude/CLAUDE.md`, `~/.claude/rules/*.md` | + +If instructions conflict, state precedence explicitly in the more specific file. Alternatively inject context via `systemPrompt` — see [[wiki/agent-sdk/modifying-system-prompts|modifying-system-prompts]]. + +## Skills + +- Discovered from `.claude/skills/` via `settingSources` +- Descriptions loaded at startup; full content loads on demand +- `"Skill"` tool is enabled by default unless you use an `allowedTools` allowlist (then add it explicitly) + +```python +options=ClaudeAgentOptions( + setting_sources=["user", "project"], + allowed_tools=["Skill", "Read", "Grep", "Glob"], +) +``` + +Skills are filesystem artifacts (`SKILL.md`) — no programmatic registration API. See [[wiki/agent-sdk/skills-in-sdk|skills-in-sdk]]. + +## Hooks + +Two types run side by side: + +| Type | Best for | Scope | +|------|---------|-------| +| **Filesystem** (`settings.json`) | Shared CLI + SDK hooks; supports `command`, `http`, `prompt`, `agent` types | Main agent + all subagents | +| **Programmatic** (callbacks in `query()`) | App-specific logic, structured decisions, in-process integration | Main session only | + +```python +async def audit_bash(input_data, tool_use_id, context): + if "rm -rf" in input_data.get("tool_input", {}).get("command", ""): + return {"decision": "block", "reason": "Destructive command blocked"} + return {} # empty dict = allow + +options=ClaudeAgentOptions( + setting_sources=["project"], # loads hooks from .claude/settings.json + hooks={ + "PreToolUse": [HookMatcher(matcher="Bash", hooks=[audit_bash])] + }, +) +``` + +TypeScript SDK adds extra events: `SessionStart`, `SessionEnd`, `TeammateIdle`, `TaskCompleted`. See [[wiki/agent-sdk/sdk-hooks|sdk-hooks]]. + +## Feature Selection Guide + +| Goal | Feature | SDK surface | +|------|---------|-------------| +| Project conventions always present | CLAUDE.md | `settingSources: ["project"]` | +| Reference material loaded when relevant | Skills | `settingSources` + `allowedTools: ["Skill"]` | +| Reusable workflow (deploy, review) | User-invocable skills | same as above | +| Isolated subtask, fresh context | Subagents | `agents` param + `allowedTools: ["Agent"]` | +| Coordinate multiple Claude Code instances | Agent teams (CLI feature) | not SDK-configurable | +| Deterministic logic on tool calls | Hooks | `hooks` callbacks or `settings.json` | +| External service with structured tools | MCP | `mcpServers` parameter | + +**Context cost reminder:** every enabled feature adds to the context window. See the features-overview cost analysis. + +## Key Takeaways + +- `settingSources` selects which filesystem locations load — omit it for full parity with the CLI, pass `[]` for programmatic-only +- Three inputs always load regardless of `settingSources`: managed policy, `~/.claude.json`, auto memory +- CLAUDE.md levels are additive; write non-conflicting rules or state precedence explicitly +- Skills load descriptions at startup, full content on demand — include `"Skill"` in `allowedTools` when using an allowlist +- Filesystem hooks and programmatic hooks coexist; filesystem hooks propagate to subagents, programmatic do not +- For multi-tenant deployments: isolated filesystem + `settingSources: []` + disable auto memory + +## Sources + +- `raw/Use Claude Code features in the SDK.md`