From claudemd
Complete official documentation for the Claude Agent SDK — building production AI agents in Python and TypeScript with the same tools, agent loop, and context management that power Claude Code. Use when working with `query()`, `ClaudeSDKClient`, `ClaudeAgentOptions`, hooks, subagents, MCP servers, sessions, permissions, custom tools, streaming, structured outputs, cost tracking, hosting, and SDK API references.
How this skill is triggered — by the user, by Claude, or both
Slash command
/claudemd:agent-sdk-docThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides the complete official documentation for the Claude Agent SDK — a Python and TypeScript library for building autonomous AI agents that read files, run commands, search the web, edit code, and more.
references/claude-code-agent-sdk-agent-loop.mdreferences/claude-code-agent-sdk-claude-code-features.mdreferences/claude-code-agent-sdk-cost-tracking.mdreferences/claude-code-agent-sdk-custom-tools.mdreferences/claude-code-agent-sdk-file-checkpointing.mdreferences/claude-code-agent-sdk-hooks.mdreferences/claude-code-agent-sdk-hosting.mdreferences/claude-code-agent-sdk-mcp.mdreferences/claude-code-agent-sdk-migration-guide.mdreferences/claude-code-agent-sdk-modifying-system-prompts.mdreferences/claude-code-agent-sdk-observability.mdreferences/claude-code-agent-sdk-overview.mdreferences/claude-code-agent-sdk-permissions.mdreferences/claude-code-agent-sdk-plugins.mdreferences/claude-code-agent-sdk-python.mdreferences/claude-code-agent-sdk-quickstart.mdreferences/claude-code-agent-sdk-secure-deployment.mdreferences/claude-code-agent-sdk-session-storage.mdreferences/claude-code-agent-sdk-sessions.mdreferences/claude-code-agent-sdk-skills.mdThis skill provides the complete official documentation for the Claude Agent SDK — a Python and TypeScript library for building autonomous AI agents that read files, run commands, search the web, edit code, and more.
| Language | Package | Requires |
|---|---|---|
| TypeScript | npm install @anthropic-ai/claude-agent-sdk | Node.js 18+ |
| Python | pip install claude-agent-sdk | Python 3.10+ |
The TypeScript SDK bundles a native Claude Code binary as an optional dependency — no separate CLI install needed.
# Python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
// TypeScript
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
if ("result" in message) console.log(message.result);
}
| Provider | Environment variable(s) |
|---|---|
| Anthropic (direct) | ANTHROPIC_API_KEY |
| Amazon Bedrock | CLAUDE_CODE_USE_BEDROCK=1 + AWS credentials |
| Claude Platform on AWS | CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID + AWS credentials |
| Google Vertex AI | CLAUDE_CODE_USE_VERTEX=1 + GCP credentials |
| Microsoft Azure | CLAUDE_CODE_USE_FOUNDRY=1 + Azure credentials |
| Tool | What it does |
|---|---|
Read | Read files in the working directory |
Write | Create new files |
Edit | Make precise edits to existing files |
Bash | Run terminal commands, scripts, git operations |
Monitor | Watch a background script and react to each output line |
Glob | Find files by pattern (**/*.ts, src/**/*.py) |
Grep | Search file contents with regex |
WebSearch | Search the web for current information |
WebFetch | Fetch and parse web page content |
AskUserQuestion | Ask the user clarifying questions with multiple-choice options |
Agent | Spawn subagents for focused subtasks |
Skill | Invoke skills |
TaskCreate / TaskUpdate | Track background tasks |
ToolSearch | Dynamically find and load deferred tool schemas on demand |
ClaudeAgentOptions / Options fields| Option (Python / TypeScript) | Type | Description |
|---|---|---|
allowed_tools / allowedTools | list[str] / string[] | Auto-approve these tools without prompting |
disallowed_tools / disallowedTools | list[str] / string[] | Block these tools; bare name removes from context, scoped rule (Bash(rm *)) denies matching calls |
permission_mode / permissionMode | PermissionMode | Controls what happens to tools not covered by allow/deny rules |
system_prompt / systemPrompt | str / string | Custom system prompt (or preset object for Claude Code's prompt) |
max_turns / maxTurns | int / number | Cap agentic turns (tool-use round trips) |
max_budget_usd / maxBudgetUsd | float / number | Stop when client-side cost estimate reaches this USD value |
effort | str | Reasoning depth: "low", "medium", "high", "xhigh", "max" |
model | str | Model alias or full ID to use |
resume | str | Session ID to resume |
continue_conversation / continue | bool | Resume the most recent session in the current directory |
fork_session / forkSession | bool | When resuming, fork to a new session instead of modifying the original |
mcp_servers / mcpServers | dict / Record | MCP server configurations |
agents | dict / Record | Programmatically defined subagents |
hooks | dict / Record | Hook callbacks keyed by event name |
setting_sources / settingSources | list / array | Which filesystem sources to load ("user", "project", "local") |
cwd | str | Working directory for the agent |
skills | list / string[] | 'all' | Skills to load; 'all' enables every discovered skill |
plugins | list / SdkPluginConfig[] | Local plugins to load |
output_format / outputFormat | object | Structured output schema (JSON Schema) |
enable_file_checkpointing / enableFileCheckpointing | bool | Track file changes for rewind |
session_store / sessionStore | SessionStore | Mirror transcripts to external storage |
persist_session / persistSession | bool | When false, disable session persistence to disk (TypeScript only) |
| Mode | Behavior | Use case |
|---|---|---|
"default" | Unlisted tools trigger canUseTool callback; no callback means deny | Custom approval flows |
"acceptEdits" | Auto-approves file edits and common filesystem commands | Trusted development workflows |
"plan" | Claude explores and plans; file edits always prompt | Read + plan without writing |
"dontAsk" | Never prompts; tools not pre-approved are denied | Locked-down headless agents |
"auto" (TypeScript only) | Model classifier approves or denies each tool call | Autonomous agents with safety guardrails |
"bypassPermissions" | All allowed tools run without asking; explicit ask rules still prompt | Sandboxed CI / fully trusted environments |
disallowedTools) — blocks regardless of modesettings.json) — falls through to canUseToolbypassPermissions approves; acceptEdits approves file opsallowedTools) — auto-approvescanUseTool callback — last resort; denied in dontAsk mode| Python class | TypeScript type field | When emitted |
|---|---|---|
SystemMessage (subtype "init") | "system" / subtype: "init" | First message; session metadata, tools, model |
AssistantMessage | "assistant" | Each Claude response (text + tool calls) |
UserMessage | "user" | Tool results fed back to Claude; user stream input |
ResultMessage | "result" | End of loop; final text, cost, session ID |
StreamEvent (partial) | "stream_event" | Raw streaming deltas (requires includePartialMessages) |
| Subtype | Meaning | result field? |
|---|---|---|
success | Task completed normally | Yes |
error_max_turns | Hit maxTurns limit | No |
error_max_budget_usd | Hit maxBudgetUsd limit | No |
error_during_execution | API failure or cancelled request | No |
error_max_structured_output_retries | No valid structured output within retry limit | No |
All result subtypes carry total_cost_usd, usage, num_turns, and session_id.
| Goal | Python | TypeScript |
|---|---|---|
| Single call, no follow-up | query() | query() |
| Multi-turn in one process | ClaudeSDKClient | query() with continue: true |
| Resume most recent session | continue_conversation=True | continue: true |
| Resume a specific session | resume="<session-id>" | resume: "<session-id>" |
| Fork a session | fork_session=True (with resume) | forkSession: true (with resume) |
| List past sessions | list_sessions() | listSessions() |
| Read past transcript | get_session_messages() | getSessionMessages() |
| Rename session | rename_session() | renameSession() |
| Tag session | tag_session() | tagSession() |
Sessions are stored as JSONL at ~/.claude/projects/<project>/<session-id>.jsonl. Suppress with persist_session=False (TypeScript) or CLAUDE_CODE_SKIP_PROMPT_HISTORY.
| Event | Fires when | Common use |
|---|---|---|
PreToolUse | Before a tool executes | Validate inputs, block dangerous commands |
PostToolUse | After a tool returns | Audit outputs, trigger side effects |
PostToolUseFailure | After a tool fails | Error handling |
PostToolBatch | After a batch of tool calls finishes | Aggregate results |
UserPromptSubmit | When a prompt is sent | Inject additional context |
Stop | When the agent finishes | Validate result, save state |
SessionStart / SessionEnd | Session lifecycle | Resource management |
SubagentStart / SubagentStop | Subagent spawns or completes | Track parallel tasks |
PreCompact | Before context compaction | Archive full transcript |
Notification | Agent sends a notification | Forward to external systems |
PermissionRequest | Permission check required | Custom approval UI |
Setup | Initialization phase | Pre-configure environment |
Hooks are registered in options.hooks as a dict/object keyed by event name. Each entry is a list of matchers: { matcher: "Write|Edit", hooks: [callback] }. A bare hook (no matcher) runs for every event of that type.
Hook callbacks return an output object:
{} — allow, no change{ decision: "block", reason: "..." } — block the tool call (Python: permissionDecision: "deny"){ decision: "approve" } — explicitly approve{ additionalContext: "..." } — inject text into the next user messageDefine agents in the agents option. Claude invokes them via the Agent tool — include "Agent" in allowedTools to auto-approve invocations.
# Python
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="Expert code reviewer for quality and security reviews.",
prompt="Analyze code quality and suggest improvements.",
tools=["Read", "Glob", "Grep"],
)
},
)
AgentDefinition fields: description (required), prompt (required), tools, disallowedTools, model, mcpServers, skills, maxTurns, background, effort, permissionMode.
Each subagent runs in a fresh conversation — intermediate tool calls don't accumulate in the parent's context. The parent receives only the subagent's final message.
# Stdio (local process)
mcp_servers={"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}}
# HTTP
mcp_servers={"api": {"type": "http", "url": "https://mcp.example.com/mcp"}}
# SSE (deprecated)
mcp_servers={"legacy": {"type": "sse", "url": "https://mcp.example.com/sse"}}
Use strict_mcp_config=True / strictMcpConfig: true to ignore project .mcp.json and load only the servers you pass programmatically. MCP tool names follow mcp__<server-name>__<tool-name>. Use wildcards in allowedTools: "mcp__myserver__*".
TypeScript: use tool() to create a Zod-typed tool definition, then createSdkMcpServer() to package it:
import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
const myTool = tool("lookup", "Look up a value", { key: z.string() },
async ({ key }) => ({ content: [{ type: "text", text: `value for ${key}` }] })
);
const server = createSdkMcpServer({ name: "my-tools", tools: [myTool] });
// Pass: mcpServers: { "my-tools": server }
Python uses @tool decorator on async functions and create_sdk_mcp_server().
Pass output_format / outputFormat with a JSON Schema to get schema-constrained results in ResultMessage.structured_output:
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
output_format={
"type": "json_schema",
"schema": {
"type": "object",
"properties": {"summary": {"type": "string"}, "bugs": {"type": "array"}},
"required": ["summary", "bugs"]
}
}
)
Enable include_partial_messages=True / includePartialMessages: true to receive StreamEvent messages with raw text deltas as Claude generates them.
To collect the full result without streaming, iterate the generator to completion — the ResultMessage is the final event.
ResultMessage fields for cost:
total_cost_usd — client-side USD estimate for the sessionusage — { input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens }modelUsage — per-model breakdown (TypeScript); model_usage (Python)Set max_budget_usd / maxBudgetUsd to stop the agent when cost exceeds a threshold.
Set enable_file_checkpointing=True / enableFileCheckpointing: true to track file changes at each user message boundary. Call query.rewindFiles(userMessageId) (TypeScript) to restore files to their state at a given point. Pass { dryRun: true } to preview changes before applying.
compact_boundary system message.# Summary instructions section to CLAUDE.md to tell the compactor what to preserve.settingSources: ["project"] to include CLAUDE.md instructions without user settings bleeding in.effort: "low" for simple read-only agents to reduce cost and latency.| Level | Behavior | Good for |
|---|---|---|
"low" | Minimal reasoning | File lookups, listing directories |
"medium" | Balanced | Routine edits, standard tasks |
"high" | Thorough analysis | Refactors, debugging |
"xhigh" | Extended depth | Coding and agentic tasks |
"max" | Maximum depth | Multi-step problems |
Query object methodsThe object returned by query() extends AsyncGenerator and exposes:
| Method | Description |
|---|---|
interrupt() | Interrupt the query (streaming input mode only) |
rewindFiles(userMessageId) | Restore files to a checkpoint |
setPermissionMode(mode) | Change permission mode mid-session |
setModel(model) | Change model mid-session |
applyFlagSettings(settings) | Merge settings into the flag layer at runtime |
initializationResult() | Get full init data (commands, models, agents) |
supportedModels() | List available models |
supportedAgents() | List defined subagents |
mcpServerStatus() | Status of connected MCP servers |
setMcpServers(servers) | Replace MCP server set dynamically |
streamInput(stream) | Send input to a multi-turn conversation |
stopTask(taskId) | Stop a running background task |
close() | Terminate the underlying process |
ClaudeSDKClientFor multi-turn conversations within a single process. Each client.query() call continues the same session automatically.
async with ClaudeSDKClient(options=ClaudeAgentOptions(allowed_tools=["Read"])) as client:
await client.query("Analyze auth.py")
async for msg in client.receive_response():
...
await client.query("Now refactor it")
async for msg in client.receive_response():
...
startup() — pre-warm subprocessimport { startup } from "@anthropic-ai/claude-agent-sdk";
const warm = await startup({ options: { maxTurns: 3 } });
for await (const message of warm.query("What files are here?")) {
console.log(message);
}
Spawns the CLI subprocess early so the first query() call has no startup latency.
| Value | Location | Contains |
|---|---|---|
"user" | ~/.claude/settings.json | Global user preferences |
"project" | .claude/settings.json | Shared project settings, CLAUDE.md |
"local" | .claude/settings.local.json | Local-only overrides |
Pass settingSources: [] to disable all filesystem settings. Managed policy settings load regardless.
When setting sources are enabled (default), the SDK loads:
CLAUDE.md — project instructions injected into every request.claude/skills/ — skills Claude can use.claude/agents/ — subagent definitions.claude/settings.json — permissions and hooks.mcp.json — MCP server configurationcwd, env, and allowedTools to isolate the working directory. Use settingSources: [] to ignore local config.permissionMode: "bypassPermissions" with allowDangerouslySkipPermissions: true in trusted sandboxes.spawnClaudeCodeProcess (TypeScript) to run in VMs, containers, or remote environments.| Variable | Description | Default |
|---|---|---|
API_TIMEOUT_MS | Per-request timeout (ms) | 600000 |
CLAUDE_CODE_MAX_RETRIES | Max API retries | 10 |
CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS | Stall watchdog for background subagents | 600000 |
CLAUDE_ENABLE_STREAM_WATCHDOG | Enable idle stream watchdog | Off by default |
CLAUDE_STREAM_IDLE_TIMEOUT_MS | Stream idle timeout | 300000 |
Pass via env: { ...process.env, API_TIMEOUT_MS: "120000" } in TypeScript options.
For the complete official documentation, see the reference files:
query(), startup(), tool(), createSdkMcpServer(), listSessions(), getSessionMessages(), resolveSettings(), all Options fields, message types, hook typesquery(), ClaudeSDKClient, ClaudeAgentOptions, message classes, hook typescanUseTool callbackClaudeSDKClient, cross-host resumption, listSessions, getSessionMessagesAgentDefinitionmcpServers config, tool naming, tool search, authentication, error handlingtool(), createSdkMcpServer(), annotations, parallel executionincludePartialMessagesoutputFormat / output_format, JSON Schema constraintstotal_cost_usd, usage, modelUsage, maxBudgetUsdenableFileCheckpointing, rewindFiles(), dry-run previewsettingSources, CLAUDE.md, skills, agents, hooks, and what each controlsskills option, the Skill tool/compact as SDK prompts, available commandscanUseTool callback, AskUserQuestion tool, onElicitationTaskCreate, TaskUpdate, background task progressENABLE_TOOL_SEARCH, alwaysLoadSdkPluginConfigincludeHookEvents, agentProgressSummaries, forwardSubagentTextsessionStore, external backends, SessionStore interfacespawnClaudeCodeProcess, timeout configurationProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub hlibkoval/claudemd --plugin claudemd