Open Claude Agent SDK

A compatible open-source replacement for @anthropic-ai/claude-agent-sdk — thin wrapper that uses your local Claude CLI.

Why?

Same API, same types — open and debuggable.

Install

bun add open-claude-agent-sdk

# Requires Claude CLI
npm install -g @anthropic-ai/claude-code

Usage

import { query } from 'open-claude-agent-sdk';

for await (const msg of query({
  prompt: 'Write a haiku about coding',
  options: { maxTurns: 3 }
})) {
  if (msg.type === 'assistant') {
    console.log(msg.message.content);
  }
  if (msg.type === 'result') break;
}

Drop-in replacement — just change the import:

- import { query } from '@anthropic-ai/claude-agent-sdk';
+ import { query } from 'open-claude-agent-sdk';

Features

Core

• Query modes — one-shot, multi-turn (AsyncIterable + streamInput), streaming
• Control methods — interrupt, close, setModel, setPermissionMode, setMaxThinkingTokens
• Query methods — supportedCommands, supportedModels, accountInfo, mcpServerStatus
• Structured outputs — JSON schema with outputFormat
• Extended thinking — maxThinkingTokens option
• System prompts — string, preset (claude_code), preset with append
• Permission callbacks — canUseTool with allow/deny/selective/async
• AbortController — signal-based cancellation
• Session management — resume, fork, continue, custom sessionId
• Cost tracking — total_cost_usd, usage, modelUsage

MCP Servers

• In-process SDK servers — createSdkMcpServer() + tool() helper with Zod schemas
• Process-based servers — stdio MCP server config via mcpServers option
• Control methods — reconnectMcpServer(), toggleMcpServer(), setMcpServers()

Subagents & Hooks

• Programmatic subagents — agents option, Task tool invocation, parent_tool_use_id
• Hooks — 7 of 26 events tested E2E (PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, plus matchers)
• Skills & commands — via settingSources + .claude/ directories
• Output styles — custom styles via .claude/output-styles/
• Sandbox — sandbox configuration pass-through

Open SDK Extensions

Extra convenience methods beyond the official SDK:

import { query, type ExtendedQuery } from 'open-claude-agent-sdk';

const q = query({ prompt: '...' }) as ExtendedQuery;

await q.availableOutputStyles(); // string[]
await q.currentOutputStyle();    // string

Subpath Exports

Lightweight entry points to avoid loading unused dependencies:

import { query } from 'open-claude-agent-sdk/query';           // query() only, no MCP
import { createSdkMcpServer, tool } from 'open-claude-agent-sdk/mcp'; // MCP utilities
import { listSessions } from 'open-claude-agent-sdk/storage';  // session storage API

Not Yet Implemented

• rewindFiles() — no CLI protocol support
• Agent teams — experimental, no env var support

See FEATURES.md for full status matrix.

Demos

Three demo apps ported from the official SDK, running on both SDKs:

# Hello world
bun demos/open/hello-world/hello-world.ts

# Interactive chat (has its own dev server)
cd demos/open/simple-chatapp && npm install && npm run dev

# Resume generator
bun demos/open/resume-generator/resume-generator.ts

Testing

# Integration tests (primary)
bun test tests/integration/

# Unit tests (SDK compatibility)
bun test tests/unit/

# Type check
bun run typecheck

Documentation

• API Reference — query function, message types, examples
• Options Reference — all query options
• Feature Matrix — full feature comparison
• Migration Guide — migrate from official SDK

License

MIT