Skip to main content
The Claude Code SDK lets you run the same agent loop that powers the CLI inside your own process. Instead of spawning the claude binary and scraping its output, you import a function, pass a prompt, and iterate over a typed stream of messages.

​
When to use the SDK vs the CLI

  • You need to process Claude’s output programmatically in the same process
  • You want to define custom tools that run in-process without a separate MCP server
  • You are building a long-running service that manages multiple sessions
  • You need fine-grained control over permissions, model selection, or abort signals
  • You want to access session history via listSessions or getSessionMessages
  • You want a one-shot command in a shell script or CI pipeline
  • You do not need to process structured output from individual messages
  • You are prototyping and want the fastest path to a working agent

​
Installation

npm install @anthropic-ai/claude-code
The SDK requires Node.js 18 or later. Set your API key before running: 
export ANTHROPIC_API_KEY=sk-ant-...

​
Basic setup

The primary entry point is query(). It accepts a prompt and returns an async generator that yields typed SDKMessage objects as the agent works through a task. 
import { query } from '@anthropic-ai/claude-code'

const messages = query({
  prompt: 'List the TypeScript files in this directory.',
  options: {
    model: 'claude-opus-4-5',
    cwd: process.cwd(),
  },
})

for await (const message of messages) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if (block.type === 'text') {
        console.log(block.text)
      }
    }
  }

  if (message.type === 'result') {
    console.log('Done. Cost:', message.total_cost_usd)
    break
  }
}

​
Message types

Every value the generator yields is an SDKMessage. The most important subtypes are:
TypeWhen it appears
system (subtype init)First message in every stream. Contains the model, tools, and MCP server list.
assistantEach assistant turn. The message.content array holds text, tool-use, and thinking blocks.
userTool results returned to Claude after a tool call.
tool_progressProgress heartbeat emitted during long-running tool calls.
result (subtype success)Final message. Contains cost, usage, and the text result.
result (subtype error_*)Final message when the agent exits with an error (max turns, budget, etc.).
system (subtype api_retry)Emitted when an API call fails and will be retried.
The stream_event type carries raw RawMessageStreamEvent objects from the Anthropic SDK. You can use these for token-level streaming if you need sub-turn granularity.

​
What’s in the SDK

The SDK exports the following public API surface:
ExportDescription
query()Core agent loop. Returns an async generator of SDKMessage.
tool()Define a custom in-process tool backed by a Zod schema.
createSdkMcpServer()Bundle custom tools into an in-process MCP server.
unstable_v2_createSession()V2 API: create a persistent multi-turn session.
unstable_v2_resumeSession()V2 API: resume an existing session by ID.
unstable_v2_prompt()V2 API: one-shot convenience wrapper.
listSessions()List session metadata across one project or all projects.
getSessionInfo()Read metadata for a single session.
getSessionMessages()Read the full message history from a session transcript.
renameSession()Rename a session.
tagSession()Tag a session (or clear its tag).
forkSession()Fork a session into a new branch at an optional message boundary.
AbortErrorError class thrown when a query is aborted.

​
Next steps

query()

Full parameter reference for the core agent function.

Sessions V2

Persistent multi-turn sessions and session management utilities.

Custom tools

Define in-process tools with Zod schemas and wire them up via MCP.

CLI flags

CLI flags that mirror SDK options for shell-based workflows.

Build docs developers (and LLMs) love

Get started for freeTalk to us