Agent SDK reference - TypeScript - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Installation npm install @anthropic-ai/claude-agent-sdk The SDK bundles a native Claude Code binary for your platform as an optional dependency such as @anthropic-ai/claude-agent-sdk-darwin-arm64 .
Most installs need no separate Claude Code install. The SDK version tracks the bundled Claude Code version. SDK v0.3.191 bundles Claude Code v2.1.191, so a feature on this page that requires a Claude Code version needs the SDK release with the same patch number or later. If your package manager skips optional dependencies, the SDK throws Native CLI binary for <platform>-<arch> not found ; set pathToClaudeCodeExecutable to a separately installed claude binary instead.
If your package manager doesn’t apply npm’s libc field, as Yarn 1.x doesn’t, you get both the glibc and musl platform packages on Linux, roughly doubling the install size. On Agent SDK v0.2.141 or later, the SDK still launches the correct variant. To reclaim the space in a container image, delete the platform package that doesn’t match the libc where your app runs; for a glibc runtime on x64, that’s rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl .
On a development machine the deletion is temporary, since Yarn reinstalls the package on the next dependency change. Compile to a single executable When you compile your application into a single-file executable with bun build --compile , the SDK cannot resolve the bundled CLI binary at runtime. require.resolve does not work inside the compiled executable’s $bunfs virtual filesystem, so the SDK throws Native CLI binary for <platform>-<arch> not found .
To work around this, embed the platform binary as a file asset, extract it to a real path at startup with extractFromBunfs() , and pass that path to pathToClaudeCodeExecutable . The extractFromBunfs() helper requires @anthropic-ai/claude-agent-sdk v0.3.144 or later. The example below builds for macOS on Apple Silicon: import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type : "file" }; import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract" ; import { query } from "@anthropic-ai/claude-agent-sdk" ; const cliPath = extractFromBunfs ( binPath ); for await ( const message of query ({ prompt: "Hello" , options: { pathToClaudeCodeExecutable: cliPath }, })) { console . log ( message ); } extractFromBunfs() copies the embedded binary out of the compiled executable’s virtual filesystem to a per-user temp directory and returns the real path.
Outside a compiled executable it returns the input path unchanged, so the same code runs in development without modification. Each compiled executable embeds a single platform’s binary. Match the platform package in the import to your --target : To cross-compile, install the non-matching platform package, for example npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force . On Windows, the binary subpath is claude.exe , for example @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe .
Import the /core entry when you bundle the Agent SDK If your application bundles the Agent SDK together with its own dependencies, import from @anthropic-ai/claude-agent-sdk/core instead of the package root. The /core entry requires TypeScript Agent SDK v0.3.282 or later, and its types require TypeScript 5.0 or later. To keep the code your application loads small, the /core entry leaves out some root exports: Exported : the same query() , startup() , prewarm() , tool() , createSdkMcpServer() , and resolveSettings() as the root entry, along with the functions that rename, tag, and delete sessions, AbortError , the runtime constants, and every type.
Importing the alpha prewarm() from /core requires Agent SDK v0.3.314 or later. Left out : root exports including the InMemorySessionStore class and the helpers that list, read, fork, import, and summarize sessions. If you need one of them, use the root entry instead. The root entry inlines its own copies of zod and @modelcontextprotocol/sdk . The /core entry imports them from your node_modules at the ranges the Agent SDK’s peerDependencies declare, so a bundle that already includes them doesn’t carry a second copy.
Import from either the root or /core in a given process, not both: they are separate bundles, and loading both gives you two copies of the Agent SDK’s classes and state. Functions query() The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive. function query ({ prompt , options } : { prompt : string | AsyncIterable < SDKUserMessage >; options ?: Options ; }) : Query ; Parameters Parameter Type Description prompt string | AsyncIterable< SDKUserMessage > The input prompt as a string or async iterable for streaming mode options Options Optional configuration object (see Options type below) Returns Returns a Query object that extends AsyncGenerator< SDKMessage , void> with additional methods. startup() Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available.
The returned WarmQuery handle accepts a prompt later and writes it to an already-ready process, so the first query() call resolves without paying subprocess spawn and initialization cost inline. If you don’t know the session’s working directory yet, use prewarm() instead. function startup ( params ?: { options ?: Options ; initializeTimeoutMs ?: number ; }) : Promise < WarmQuery >; Parameters Parameter Type Description options Options Optional configuration object.
Same as the options parameter to query() initializeTimeoutMs number Maximum time in milliseconds to wait for subprocess initialization. Defaults to 60000 . If initialization does not complete in time, the promise rejects with a timeout error Slow SessionStart and Setup command hooks get extra time only when initializeTimeoutMs is unset: If you leave it unset: time these hooks spend running doesn’t count toward the 60-second default, up to 10 minutes in total, so initialization can take 11 minutes at most.
If you set a value, including 60000 : that value is the limit, even while a hook is running. The extra time requires TypeScript Agent SDK v0.3.304 or later. Returns Returns a Promise< WarmQuery > that resolves once the subprocess has spawned and completed its initialize handshake. Of the hook_progress messages a SessionStart or Setup hook emits before the handshake completes, you get only the newest, which carries all of the hook’s output so far. startup() holds that message, the hook’s hook_started message, and anything else the subprocess emits before the handshake completes.
The held messages reach you once you call .query() on the WarmQuery and iterate the result. Example Call startup() early, for example on application boot, then call .query() on the returned handle once a prompt is ready. This moves subprocess spawn and initialization out of the critical path. import { startup } from "@anthropic-ai/claude-agent-sdk" ; // Pay startup cost upfront const warm = await startup ({ options: { maxTurns: 3 } }); // Later, when a prompt is ready, this is immediate for await ( const message of warm . query ( "What files are here?" )) { console . log ( message ); } prewarm() Alpha.
Starts a Claude Code process as a spare before you know which session it will serve, so you can bind it to a session later with claim() . Requires TypeScript Agent SDK v0.3.282 or later. Use prewarm() when your application boots before the user picks a folder. function prewarm ( params ?: { options ?: Options ; initializeTimeoutMs ?: number ; }) : Promise < SpareProcess >; Parameters Parameter Type Description options Options Optional configuration object, the same type that startup() takes initializ
The rest of this page is on the live site.