Claude Code Sdk

Claude Code SDK

Authoritative reference for Claude Code extensibility and configuration. Use this skill when building, configuring, or debugging any Claude Code extension mechanism.

References

• Skills — [${CLAUDE_SKILL_DIR}/references/skills.md] frontmatter fields, invocation control matrix, paths:

shared mechanic with rules, skillOverrides setting, string substitutions, dynamic context injection, subagent execution via fork, compaction budget, description budget (1,536-char per-entry, 1% context aggregate), bundled skills

• Rules — [${CLAUDE_SKILL_DIR}/references/rules.md] .claude/rules/*.md discovery (recursive), two loading modes

(unconditional = launch-time priority; conditional via paths:), paths: syntax (comma-string OR YAML list), project vs personal scope, InstructionsLoaded hook with all 5 matchers, sharing patterns, claudeMdExcludes

• Plugins — [${CLAUDE_SKILL_DIR}/references/plugins.md] plugin.json schema (incl. dependencies array v2.1.110+,

experimental.monitors v2.1.105+, experimental.themes v2.1.118+), directory layout, ${CLAUDE_PLUGIN_ROOT}/_DATA env vars, marketplace.json (5 source types + allowCrossMarketplaceDependenciesOn), LSP server configs, bin/ PATH contract, claude plugin tag --push and claude plugin prune, allowedChannelPlugins managed setting

• Hooks — [${CLAUDE_SKILL_DIR}/references/hooks.md] all 29 events with input/output JSON schemas and matcher

values, 5 hook types (command, http, prompt, agent, mcp_tool) with handler fields, exit code blocking table (incl. PreCompact blocking v2.1.105+), async hooks, decision control patterns, security

• Subagents — [${CLAUDE_SKILL_DIR}/references/subagents.md] 5 built-in agents, custom agent frontmatter, tool

control, MCP scoping, worktree isolation, invocation methods, agent teams (architecture, tasks, messaging, hooks, lifecycle)

• MCP — [${CLAUDE_SKILL_DIR}/references/mcp.md] .mcp.json schema, 3 transports (HTTP/SSE/stdio), scopes and

precedence, OAuth (incl. headersHelper), env var expansion, managed config, tool search, alwaysLoad (v2.1.121+), 2KB description cap, anthropic/maxResultSizeChars per-tool override, elicitation, resources, prompts as commands

• Memory — [${CLAUDE_SKILL_DIR}/references/memory.md] full .claude directory tree, CLAUDE.md hierarchy and

loading order, @import syntax (max depth 5), auto memory (MEMORY.md 200-line/25KB cap), path-specific rules

• Settings — [${CLAUDE_SKILL_DIR}/references/settings.md] 5-level scope hierarchy, server-managed settings

(v2.1.30 Enterprise / v2.1.38 Teams), 50+ settings keys, permission rule syntax per tool type, 6 permission modes, sandbox config (filesystem/network isolation), claude project purge (v2.1.126), expanded protected paths

• Auto Mode — [${CLAUDE_SKILL_DIR}/references/auto-mode.md] classifier mechanics (Sonnet 4.6 background, never

sees tool results), prompt-injection resistance, default block lists, failure modes (3-consecutive / 20-total circuit breaker), autoMode.{environment,allow,soft_deny} config (v2.1.118+ $defaults sentinel), CLI subcommands, enterprise lockdown

• Cloud — [${CLAUDE_SKILL_DIR}/references/cloud.md] surface comparison (versions, plans, provider restrictions),

Routines (v2.1.105+, schedule/API/GitHub triggers, /fire endpoint), Ultraplan (v2.1.91+), Ultrareview (v2.1.86+ with pricing tier), Remote Control (v2.1.51+ vs --teleport), Claude Code on the Web, Code Review, Computer Use (v2.1.85+ macOS-only)

• Model config — [${CLAUDE_SKILL_DIR}/references/model-config.md] aliases (incl. [1m] variants), effort levels

(low/medium/high/xhigh/max — available levels depend on the model), opusplan hybrid routing, third-party provider pinning, prompt caching env vars

• Output styles — [${CLAUDE_SKILL_DIR}/references/output-styles.md] 3 built-in styles, custom style frontmatter,

keep-coding-instructions flag, system prompt modification pipeline, activation timing (session start only)

• Channels — [${CLAUDE_SKILL_DIR}/references/channels.md] MCP server contract, one-way vs two-way types, sender

gating, permission relay, console (API key) auth (v2.1.128+), allowedChannelPlugins allowlist (v2.1.84+), enterprise controls, built-in plugins (Telegram/Discord/iMessage/fakechat)

• Tools — [${CLAUDE_SKILL_DIR}/references/tools.md] built-in tools by category with permission requirements, name

patterns for permission rules, agent tool restrictions, hook matchers, skill allowed-tools

• Status line — [${CLAUDE_SKILL_DIR}/references/statusline.md] configuration fields, complete JSON input schema,

ANSI colors, OSC 8 clickable links, caching by session_id, plugin delivery

• Agent SDK — [${CLAUDE_SKILL_DIR}/references/agent-sdk.md] entry points (query/ClaudeSDKClient/

unstable_v2_* preview), session-based send/stream patterns, full options reference, sessions (continue/resume/fork), system prompt config, permissions, hooks, custom tools, MCP, subagents, streaming, structured outputs, headless init.plugin_errors schema, Claude Agent SDK v0.1.0 migration, TS↔Python differences

• Best practices — [${CLAUDE_SKILL_DIR}/references/best-practices.md] context window mechanics, verification

patterns, scheduling (/loop//proactive alias, cron tools, cloud/desktop), checkpointing and rewind, extension mechanism selection table

Read the relevant reference before making detailed changes. References provide field-level schemas, complete tables, and implementation details.

Concepts

Skill — Prompt template in SKILL.md loaded on-demand when description matches user request. Frontmatter controls invocation, tool access, model, effort (incl. xhigh where the model supports it), execution context (context: fork for subagent), scoped hooks, and paths: glob filter for file-pattern auto-activation. Supports string substitutions ($ARGUMENTS, ${CLAUDE_SKILL_DIR}, ${CLAUDE_EFFORT}) and dynamic context injection via ` !command . Per-skill description cap: 1,536 chars (raised from 250 in v2.1.105). Aggregate description budget: 1% of context window with 8,000-char fallback (override via SLASHCOMMANDTOOLCHARBUDGET). The skillOverrides setting toggles per-skill visibility/invocability in four states; the /skills` menu writes it.

Rule — Modular project context in .claude/rules/*.md (project) or ~/.claude/rules/*.md (personal). Two loading modes: without paths: loads at launch with the same priority as .claude/CLAUDE.md — use to split an overgrown CLAUDE.md into topic files. With paths: is conditional, only injected when working with files matching the glob. Discovery is recursive across subdirectories. paths: accepts a comma-separated string or a YAML list (YAML-list form added in v2.1.84). The InstructionsLoaded hook fires for each rule loaded with matchers session_start, nested_traversal, path_glob_match, include, and compact. Rules are file-triggered; skills are task-triggered. The paths: field is a shared mechanic between rules and skills — same syntax, same semantics, applied to two primitives.

Plugin — Distributable package of skills, agents, hooks, MCP servers, LSP servers, output styles, monitors, themes, and default settings. Manifest at .claude-plugin/plugin.json (only name is required when present). Skills namespaced as /plugin:skill. Two path variables: ${CLAUDE_PLUGIN_ROOT} (install dir, changes on update) and ${CLAUDE_PLUGIN_DATA} (persistent data dir). Marketplace supports 5 source types. bin/ adds executables to Bash PATH (W14 2026). Plugins ship custom color themes via experimental.themes (v2.1.118+) and background monitors via experimental.monitors (v2.1.105+; the top-level monitors key is deprecated as of v2.1.129).

Plugin Dependencies — A plugin can declare other plugins it needs in the dependencies array of plugin.json (v2.1.110+). Entries are bare strings (track latest) or objects {name, version, marketplace} with semver ranges (~, ^, >=, =). Pre-releases excluded unless opted in (^2.0.0-0). Cross-marketplace dependencies are blocked unless the target is listed in allowCrossMarketplaceDependenciesOn in the root marketplace.json. Tag releases with {plugin-name}--v{version} via claude plugin tag --push; remove orphans with claude plugin prune (v2.1.121+). plugin uninstall --prune cascades.

Hook — Deterministic automation at 29 lifecycle events. Five types: command (shell), http (POST to URL), prompt (single-turn LLM, 30s), agent (multi-turn with tools, 60s), mcp_tool (in-process MCP). Matcher patterns filter when hooks fire (exact string, pipe-delimited list, or regex). Exit code 2 blocks the operation for blocking events. PreCompact gained the ability to block as of v2.1.105. PostToolUse hookSpecificOutput.updatedToolOutput replaces tool output for ALL tools (v2.1.121, was MCP-only). All matching hooks run in parallel.

MCP Server — External tool/resource provider via Model Context Protocol. Three transports: HTTP (recommended for remote), SSE (deprecated), stdio (local processes). OAuth 2.0 for remote servers. Scope precedence: local > project > user > plugin > Claude.ai connectors. Tool search defers schema loading for large tool sets; alwaysLoad: true (v2.1.121+) bypasses deferral per server. Tool descriptions and server instructions cap at 2KB (v2.1.84+). Per-tool result-size override via anthropic/maxResultSizeChars (v2.1.91+). Supports elicitation and @server:uri resources.

Output Style — Persona/behavior modifier that replaces parts of the default system prompt — the only mechanism that does this. Built-in: Default, Explanatory, Learning. keep-coding-instructions: false (default) removes coding guidance; true appends style on top of full prompt. Applied at session start only (not mid-conversation) due to prompt caching.

CLAUDE.md / Memory — Project memory providing persistent context. Hierarchy: managed > project > user > local. Loaded by walking up from cwd. Supports @path imports (max depth 5). Auto memory: MEMORY.md (first 200 lines or 25KB) loaded each session; topic files read on demand. claudeMdExcludes skips irrelevant CLAUDE.md in monorepos. Modular content lives in rules (see Rule concept above).

Subagent — Isolated context for delegated tasks. Five built-in types: Explore (haiku, read-only), Plan (inherited model, read-only), general-purpose (inherited model, all tools), statusline-setup (sonnet), Claude Code Guide (haiku). Custom agents in .claude/agents/ with frontmatter for tools, model, MCP scoping. Invocation: automatic delegation, @-mention, --agent flag (session-wide). Subagents cannot spawn other subagents. Supports persistent memory, worktree isolation, scoped MCP servers.

Agent Teams — Multi-agent orchestration with shared task lists and inter-agent messaging. Lead creates team, spawns teammates, coordinates work. Tasks have states (pending/in_progress/completed), dependencies, and ownership. Teammates go idle between turns and wake on message. Team-specific hooks: TeammateIdle, TaskCreated, TaskCompleted. Experimental: requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Channels — Push external events into a running session via MCP servers spawned over stdio. One-way (alerts/webhooks) or two-way (chat with reply tools). Sender gating required to prevent prompt injection. Permission relay enables remote tool approval. Console (API key) auth supported as of v2.1.128+; orgs with managed settings must set channelsEnabled: true. Built-in plugins: Telegram, Discord, iMessage, fakechat. allowedChannelPlugins (v2.1.84+) is the enterprise allowlist. Research preview, requires --channels per session.

Auto Mode — Permission mode where a separate classifier model (Sonnet 4.6, background) reviews actions before they run. The auto permission mode IS the classifier. Available v2.1.83+ on Max/Team/Enterprise/API plans (Anthropic API only — not Bedrock/Vertex/Foundry). The classifier never sees tool results, so prompt injection from tool output cannot influence its decisions. Three-consecutive / 20-total denial circuit breaker. Configure trust via autoMode.{environment,allow,soft_deny} with the $defaults sentinel (v2.1.118+). Enterprise lockdown: disableAutoMode, allowManagedDomainsOnly, allowManagedReadPathsOnly, allowManagedHooksOnly.

Routines — Templated cloud agents on Anthropic infrastructure (v2.1.105+). Triggered by schedule (/schedule or /routines CLI), API call (/fire endpoint with one-time bearer token), or GitHub events (Claude GitHub App). Daily run cap with extra-usage fallback; webhook hourly caps in research preview.

Cloud Reviews — Two cloud-based review surfaces. Ultraplan (v2.1.91+) drafts complex plans in a web session for browser review; /ultraplan [prompt] or include ultraplan keyword; auto-creates default cloud env (v2.1.101+); disconnects active Remote Control. Ultrareview (v2.1.86+) runs parallel agents to find and verify bugs in a remote sandbox; /ultrareview (current branch) or /ultrareview ; pricing tier (Pro/Max 3 free runs through 2026-05-05, then $5–$20 per review extra usage). Neither runs on Bedrock/Vertex/Foundry. Local /review is a separate, simpler multi-agent local review.

Remote Control — Continue a local session from phone/tablet/browser (v2.1.51+). claude remote-control server mode, --remote-control interactive flag, or /remote-control mid-session. Distinct from --teleport (cloud-to-local session move). Org policy can disable; admin gates and "needs auth" vs "failed" status are surfaced explicitly.

Web Sessions — Run Claude Code in the cloud from claude.ai/code. --remote opts a local session into cloud sandbox; sessions move via --teleport. Local-bundle fallback via CCR_FORCE_BUNDLE=1 for repos that fail to upload.

Server-Managed Settings — Enterprise admins ship Claude Code config from the Claude.ai admin console without device management infrastructure (v2.1.30 Enterprise, v2.1.38 Teams). Server-checked first (no merge with endpoint-managed). forceRemoteSettingsRefresh enables fail-closed startup. MCP distribution and per-group config not supported.

Computer Use — macOS-only GUI automation in CLI (v2.1.85+, W14 2026). Opt-in via /mcp computer-use enable. Pro/Max plans only; Claude.ai auth required. Per-app approval with broad-reach warnings; control tiers: view-only, click-only, full. Machine-wide screenshare lock is the dominant failure mode.

Settings — Configuration hierarchy: server-managed > managed > CLI args > local > project > user. Array-valued settings (permissions, sandbox paths) concatenate and deduplicate across scopes — they do not replace. Six permission modes: default, plan, acceptEdits, auto (v2.1.83+), dontAsk, bypassPermissions. Permission evaluation: deny > ask > allow (first match wins). Sandbox provides filesystem and network isolation with allowWrite/denyWrite/allowRead/ denyRead paths.

Agent SDK — Programmatic interface for building custom agents using Claude Code as a library. TypeScript (@anthropic-ai/claude-agent-sdk, package renamed from claude-code-sdk in v0.1.0) and Python (claude-agent-sdk). Entry points: query() and ClaudeSDKClient (V1 stable); unstable_v2_createSession/unstable_v2_resumeSession/ unstable_v2_prompt with separate send/stream and await using lifecycle (V2 preview). Sessions persist via continue/resume/fork. Headless --output-format stream-json returns init.plugin_errors with both dependency demotions (v2.1.111+) and --plugin-dir failures (v2.1.128+). CLAUDE_CODE_FORK_SUBAGENT=1 works in non-interactive claude -p (v2.1.121+).

Choosing the Right Extension Mechanism

When to Use Each

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xobotyi
• Source: xobotyi/cc-foundry
• License: MIT

Install and usage instructions live in the source repository linked above.