Use Claude Code features in the SDK

The Agent SDK is built on the same foundation as Claude Code, which means your SDK agents have access to the same filesystem-based features: project instructions (CLAUDE.md and rules), skills, hooks, and more.

By default, the SDK loads no filesystem settings. Your agent runs in isolation mode with only what you pass programmatically. To load CLAUDE.md, skills, or filesystem hooks, set settingSources to tell the SDK where to look.

For a conceptual overview of what each feature does and when to use it, see Extend Claude Code.

Enable Claude Code features with settingSources

The setting sources option (setting_sources in Python, settingSources in TypeScript) controls which filesystem-based settings the SDK loads. Without it, your agent won't discover skills, CLAUDE.md files, or project-level hooks.

This example loads both user-level and project-level settings by setting settingSources to ["user", "project"]:

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")

Each source loads settings from a specific location, where <cwd> is the working directory you pass via the cwd option (or the process's current directory if unset). For the full type definition, see SettingSource (TypeScript) or SettingSource (Python).

To match the full Claude Code CLI behavior, use ["user", "project", "local"].

Project instructions (CLAUDE.md and rules)

CLAUDE.md files and .claude/rules/*.md files give your agent persistent context about your project: coding conventions, build commands, architecture decisions, and instructions. When settingSources includes "project" (as in the example above), the SDK loads these files into context at session start. The agent then follows your project conventions without you repeating them in every prompt.

CLAUDE.md load locations

All levels are additive: if both project and user CLAUDE.md files exist, the agent sees both. There is no hard precedence rule between levels; if instructions conflict, the outcome depends on how Claude interprets them. Write non-conflicting rules, or state precedence explicitly in the more specific file ("These project instructions override any conflicting user-level defaults").

For how to structure and organize CLAUDE.md content, see Manage Claude's memory.

Skills

Skills are markdown files that give your agent specialized knowledge and invocable workflows. Unlike CLAUDE.md (which loads every session), skills load on demand. The agent receives skill descriptions at startup and loads the full content when relevant.

To use skills in the SDK, set settingSources so the agent discovers skill files from the filesystem. The Skill tool is enabled by default when you don't specify allowedTools. If you are using an allowedTools allowlist, include "Skill" explicitly.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        allowed_tools=["Skill", "Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

For more on creating and using skills, see Agent Skills in the SDK.

Hooks

The SDK supports two ways to define hooks, and they run side by side:

• Filesystem hooks: shell commands defined in settings.json, loaded when settingSources includes the relevant source. These are the same hooks you'd configure for interactive Claude Code sessions.
• Programmatic hooks: callback functions passed directly to query(). These run in your application process and can return structured decisions. See Control execution with hooks.

Both types execute during the same hook lifecycle. If you already have hooks in your project's .claude/settings.json and you set settingSources: ["project"], those hooks run automatically in the SDK with no extra configuration.

Hook callbacks receive the tool input and return a decision dict. Returning {} (an empty dict) means allow the tool to proceed. Returning {"decision": "block", "reason": "..."} prevents execution and the reason is sent to Claude as the tool result. See the hooks guide for the full callback signature and return types.

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {"decision": "block", "reason": "Destructive command blocked"}
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

When to use which hook type

For full details on programmatic hooks, see Control execution with hooks. For filesystem hook syntax, see Hooks.

Choose the right feature

The Agent SDK gives you access to several ways to extend your agent's behavior. If you're unsure which to use, this table maps common goals to the right approach.

Every feature you enable adds to your agent's context window. For per-feature costs and how these features layer together, see Extend Claude Code.

Related resources

• Extend Claude Code: Conceptual overview of all extension features, with comparison tables and context cost analysis
• Skills in the SDK: Full guide to using skills programmatically
• Subagents: Define and invoke subagents for isolated subtasks
• Hooks: Intercept and control agent behavior at key execution points
• Permissions: Control tool access with modes, rules, and callbacks
• System prompts: Inject context without CLAUDE.md files