SDK overview

The Claude Code SDK is a control protocol for embedding Claude Code in other applications — IDEs, automation scripts, CI/CD pipelines, or any host that can spawn a subprocess and communicate over stdin/stdout. Rather than exposing a library API directly, the SDK communicates with a running claude process over a structured JSON message stream. The host process sends user messages and control requests; the CLI process streams back assistant messages, tool progress events, and result payloads.

The TypeScript types described on this page are exported from @anthropic-ai/claude-code under the agentSdkTypes entry point. Control protocol types (prefixed SDKControl) are @alpha and subject to change.

How it works

Spawn a Claude Code process

Start claude with --output-format stream-json and --print (non-interactive mode). Pipe its stdin and stdout into your host process.

claude --output-format stream-json --print --verbose

For a persistent session that accepts multiple prompts over time, omit --print and instead send SDKUserMessage objects to stdin after the session initializes.

Send an initialize request

Write a control_request with subtype: "initialize" to stdin. The CLI responds with an SDKControlInitializeResponse containing available commands, models, agents, and account information.

{
  "type": "control_request",
  "request_id": "init-1",
  "request": {
    "subtype": "initialize",
    "systemPrompt": "You are a code reviewer.",
    "appendSystemPrompt": "Always suggest tests."
  }
}

Stream messages from stdout

Read newline-delimited JSON from stdout. Each line is one of the SDKMessage union types — assistant turns, tool progress, system events, and result summaries.

Send user messages

Write SDKUserMessage objects to stdin to continue the conversation. Each message contains an Anthropic API-compatible message payload.

Output formats

Pass --output-format to control what Claude Code writes to stdout.

Format	Description
`text`	Plain text responses only. Default for interactive mode.
`json`	Single JSON object written at completion. Suitable for one-shot scripts.
`stream-json`	Newline-delimited JSON stream. One message per line, emitted as events occur. Required for SDK use.

Use stream-json when you need to render progress incrementally or handle tool events. Use json when you only care about the final result.

Control protocol messages

The control protocol uses two top-level envelope types that flow bidirectionally over stdin/stdout.

`SDKControlRequest`

Sent to the CLI process to configure the session or issue commands.

{
  "type": "control_request",
  "request_id": "<unique-string>",
  "request": { "subtype": "...", ...payload }
}

type

literal: 'control_request'

required

Always "control_request".

request_id

string

required

Unique identifier for this request. The CLI echoes it back in the corresponding control_response.

request

SDKControlRequestInner

required

The request payload. subtype identifies which operation to perform.

`SDKControlResponse`

Emitted from the CLI process in response to a control_request.

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "<echoed-id>",
    "response": { ...payload }
  }
}

On error, subtype is "error" and the error field contains a human-readable message.

Initialize request and response

The initialize request is the first control message you must send. It configures the session and returns available capabilities.

`SDKControlInitializeRequest`

{
  "type": "control_request",
  "request_id": "init-1",
  "request": {
    "subtype": "initialize",
    "systemPrompt": "You are a CI automation agent.",
    "appendSystemPrompt": "Always add test coverage.",
    "hooks": {
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hookCallbackIds": ["my-hook-id"]
        }
      ]
    },
    "agents": {
      "CodeReviewer": {
        "description": "Reviews code for quality and security.",
        "prompt": "You are an expert code reviewer...",
        "model": "opus"
      }
    }
  }
}

subtype

literal: 'initialize'

required

Identifies this as an initialize request.

systemPrompt

string

Replaces the default system prompt for this session.

appendSystemPrompt

string

Appended to the system prompt without replacing it. Use this to add context while keeping the default behavior.

hooks

Record<HookEvent, SDKHookCallbackMatcher[]>

Registers SDK-side hook callbacks. The CLI calls back into the SDK process when hook events fire. See Hooks reference.

sdkMcpServers

string[]

Names of in-process SDK MCP servers (created with createSdkMcpServer) to connect to this session.

agents

Record<string, AgentDefinition>

Custom subagent definitions available to the Agent tool during this session.

Show AgentDefinition fields

description

string

required

Natural language description of when Claude should invoke this agent.

prompt

string

required

System prompt for this agent.

model

string

Model alias ("sonnet", "opus", "haiku") or full model ID. Defaults to inheriting the parent model.

tools

string[]

Allow-list of tool names. When omitted, the agent inherits all tools.

disallowedTools

string[]

Tools explicitly blocked for this agent.

maxTurns

number

Maximum agentic turns before the agent stops.

permissionMode

PermissionMode

Override permission mode for this agent. See Permissions API.

`SDKControlInitializeResponse`

The CLI responds with the session’s current capabilities.

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "init-1",
    "response": {
      "commands": [...],
      "agents": [...],
      "output_style": "stream-json",
      "available_output_styles": ["text", "json", "stream-json"],
      "models": [...],
      "account": {
        "email": "[email protected]",
        "organization": "Acme Corp",
        "apiProvider": "firstParty"
      }
    }
  }
}

commands

SlashCommand[]

Available slash commands (e.g., /compact, /cost). Each entry has name, description, and argumentHint.

agents

AgentInfo[]

Available subagent types. Each has name, description, and an optional model.

output_style

string

The active output format ("stream-json", "json", "text").

models

ModelInfo[]

Available models for this account.

Show ModelInfo fields

value

string

Model identifier for API calls (e.g., "claude-sonnet-4-6").

displayName

string

Human-readable name (e.g., "Claude Sonnet 4.6").

supportsEffort

boolean

Whether this model supports effort levels.

supportsAdaptiveThinking

boolean

Whether this model supports adaptive thinking (Claude decides when and how much to think).

account

AccountInfo

Logged-in account details.

Show AccountInfo fields

string

Account email address.

organization

string

Organization name.

subscriptionType

string

Subscription tier.

apiProvider

'firstParty' | 'bedrock' | 'vertex' | 'foundry'

Active API backend. Anthropic OAuth only applies when "firstParty".

User messages

Send user messages to stdin to drive the conversation forward.

`SDKUserMessage`

{
  "type": "user",
  "message": {
    "role": "user",
    "content": "Refactor this function to use async/await."
  },
  "parent_tool_use_id": null
}

type

literal: 'user'

required

Always "user".

message

APIUserMessage

required

An Anthropic API-compatible user message. content can be a string or a content block array (for images and other media).

parent_tool_use_id

string | null

required

Tool use ID this message is responding to, or null for top-level user messages.

uuid

string

Optional UUID to track this message. Echoed back in related events.

priority

'now' | 'next' | 'later'

Scheduling hint for async message queuing.

SDK message stream types

Claude Code emits a stream of JSON messages to stdout. The type field identifies each message.

system — session initialization

Emitted once at session start with subtype: "init". Contains the active model, tool list, MCP server statuses, permission mode, and session ID.

{
  "type": "system",
  "subtype": "init",
  "model": "claude-sonnet-4-6",
  "tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep"],
  "mcp_servers": [],
  "permissionMode": "default",
  "session_id": "abc123",
  "uuid": "..."
}

assistant — model response

Emitted when the model produces a turn. Contains the full Anthropic API response object, including any tool_use blocks.

{
  "type": "assistant",
  "message": { "role": "assistant", "content": [...] },
  "parent_tool_use_id": null,
  "uuid": "...",
  "session_id": "abc123"
}

stream_event — partial streaming tokens

Emitted during streaming with RawMessageStreamEvent payloads. Use these to render incremental output.

tool_progress — long-running tool status

Emitted periodically for tools that take more than a few seconds (e.g., Bash commands). Contains tool_name, tool_use_id, and elapsed time.

result — final turn summary

Emitted at the end of each turn. subtype is "success" or one of the error subtypes.

{
  "type": "result",
  "subtype": "success",
  "result": "The function has been refactored.",
  "duration_ms": 4200,
  "total_cost_usd": 0.0042,
  "num_turns": 3,
  "is_error": false,
  "stop_reason": "end_turn",
  "session_id": "abc123",
  "uuid": "..."
}

Error subtypes: "error_during_execution", "error_max_turns", "error_max_budget_usd", "error_max_structured_output_retries".

system — status updates

Emitted with subtype: "status" when the permission mode or session status changes (e.g., "compacting").

Other control requests

Beyond initialize, the control protocol exposes these operations.

`subtype`	Direction	Description
`interrupt`	host → CLI	Interrupt the current turn.
`set_permission_mode`	host → CLI	Change the active permission mode.
`set_model`	host → CLI	Switch to a different model mid-session.
`can_use_tool`	CLI → host	Permission request for a tool call (requires SDK permission handler).
`mcp_status`	host → CLI	Get MCP server connection statuses.
`mcp_set_servers`	host → CLI	Replace dynamically managed MCP servers.
`get_context_usage`	host → CLI	Get context window usage breakdown.
`get_settings`	host → CLI	Read the effective merged settings.
`apply_flag_settings`	host → CLI	Merge settings into the flag settings layer.
`rewind_files`	host → CLI	Revert file changes made since a given message.
`hook_callback`	CLI → host	Deliver a hook event for an SDK-registered hook callback.
`reload_plugins`	host → CLI	Reload plugins from disk.

Session management API

For scripting scenarios, the SDK exports functions that operate on saved session transcripts stored in ~/.claude/.

import {
  query,
  listSessions,
  getSessionInfo,
  getSessionMessages,
  forkSession,
  renameSession,
  tagSession,
} from '@anthropic-ai/claude-code'

query — run a prompt

The primary SDK entry point. Accepts a prompt string or AsyncIterable<SDKUserMessage> and returns an async iterable of SDKMessage.

for await (const message of query({
  prompt: 'What files are in this directory?',
  options: { cwd: '/my/project' }
})) {
  if (message.type === 'result') {
    console.log(message.result)
  }
}

listSessions — list saved sessions

Returns session metadata for a project directory. Pass dir to scope to a specific project, or omit to list all sessions.

const sessions = await listSessions({ dir: '/my/project', limit: 50 })

getSessionMessages — read a transcript

Parses the JSONL transcript file for a session and returns messages in chronological order.

const messages = await getSessionMessages(sessionId, {
  dir: '/my/project',
  includeSystemMessages: false,
})

forkSession — branch a conversation

Copies a session’s transcript into a new session with remapped UUIDs. Supports upToMessageId to fork from a specific point.

const { sessionId: newId } = await forkSession(originalSessionId, {
  upToMessageId: 'msg-uuid',
  title: 'Experimental branch',
})

renameSession and tagSession

await renameSession(sessionId, 'My refactor session')
await tagSession(sessionId, 'needs-review')
await tagSession(sessionId, null) // clear tag

Use cases

IDE integration
CI/CD automation
Headless agents

IDEs can spawn a persistent Claude Code process and route messages through the control protocol. Send the initialize request with a custom systemPrompt that describes the IDE context, then forward user messages from the editor’s chat panel. Use PreToolUse hook callbacks to intercept file edits and display diffs in the IDE’s native UI before they are applied.

In CI pipelines, use --output-format json and --print for one-shot tasks:

result=$(echo "Review the diff and output pass/fail" | \
  claude --output-format json --print \
         --permission-mode bypassPermissions)

Parse the result field from the JSON output to extract the agent’s response programmatically.

For long-running background agents, use query() from the TypeScript SDK with a streaming output format. Combine with watchScheduledTasks (internal) to fire tasks on cron schedules while keeping a persistent daemon process that maintains the WebSocket connection to claude.ai.

Commands

Built-in Tools

SDK & Extensibility

How it works

Output formats

Control protocol messages

`SDKControlRequest`

`SDKControlResponse`

Initialize request and response

`SDKControlInitializeRequest`

`SDKControlInitializeResponse`

User messages

`SDKUserMessage`

SDK message stream types

Other control requests

Session management API

Use cases

Commands

Built-in Tools

SDK & Extensibility

​How it works

​Output formats

​Control protocol messages

​SDKControlRequest

​SDKControlResponse

​Initialize request and response

​SDKControlInitializeRequest

​SDKControlInitializeResponse

​User messages

​SDKUserMessage

​SDK message stream types

​Other control requests

​Session management API

​Use cases

How it works

Output formats

Control protocol messages

`SDKControlRequest`

`SDKControlResponse`

Initialize request and response

`SDKControlInitializeRequest`

`SDKControlInitializeResponse`

User messages

`SDKUserMessage`

SDK message stream types

Other control requests

Session management API

Use cases