Claude Code SDK for TypeScript

Unofficial TypeScript port of the official Python Claude Code SDK for Claude Code, the CLI tool for interacting with Claude.
Note: This is a community-maintained TypeScript port. For the official Python SDK, see claude-code-sdk.
Installation
npm install @instantlyeasy/claude-code-sdk-ts
yarn add @instantlyeasy/claude-code-sdk-ts
pnpm add @instantlyeasy/claude-code-sdk-ts
Prerequisites:
- Node.js 18 or later
- Claude Code CLI installed (
npm install -g @anthropic-ai/claude-code
)
Quick Start
New Fluent API (Recommended)
The SDK now includes a powerful fluent API that makes common tasks easier:
import { claude } from '@instantlyeasy/claude-code-sdk-ts';
const response = await claude().withModel('sonnet').skipPermissions().query('Say "Hello World!"').asText();
console.log(response);
File Operations with Fluent API
import { claude } from '@instantlyeasy/claude-code-sdk-ts';
const result = await claude()
.allowTools('Write')
.skipPermissions()
.query('Create a hello.txt file with "Hello from Claude!"')
.asResult();
console.log('Task completed:', result);
const config = await claude().allowTools('Read').query('Read package.json and return its content').asJSON();
console.log('Version:', config.version);
Session Management
Maintain conversation context across multiple queries with built-in session handling:
import { claude } from '@instantlyeasy/claude-code-sdk-ts';
const builder = claude().withModel('sonnet').skipPermissions();
const parser = builder.query('Pick a random number from 1-100');
const sessionId = await parser.getSessionId();
const firstResponse = await parser.asText();
const secondResponse = await builder.withSessionId(sessionId).query('What number did you pick?').asText();
const builder = claude().withModel('sonnet').skipPermissions();
const parser = builder.query('Tell me a fun fact');
const sessionId = await parser.getSessionId();
const fact = await parser.asText();
const follow = await builder.withSessionId(sessionId).query('Tell me more about that topic').asText();
Advanced Features
import { claude, ConsoleLogger, LogLevel } from '@instantlyeasy/claude-code-sdk-ts';
const logger = new ConsoleLogger(LogLevel.DEBUG);
const analysis = await claude()
.withModel('opus')
.allowTools('Read', 'Grep', 'Glob')
.inDirectory(process.cwd())
.withLogger(logger)
.onToolUse(tool => console.log(`Using ${tool.name}...`))
.query('Find all TODO comments in the codebase')
.asToolExecutions();
for (const execution of analysis) {
console.log(`${execution.tool}: ${execution.isError ? 'Failed' : 'Success'}`);
}
Classic API (Original Syntax)
The original async generator API is still fully supported:
import { query } from '@instantlyeasy/claude-code-sdk-ts';
for await (const message of query('Say "Hello World!"')) {
if (message.type === 'assistant') {
for (const block of message.content) {
if (block.type === 'text') {
console.log(block.text);
}
}
}
}
Authentication
This SDK delegates all authentication to the Claude CLI. There are two ways to authenticate:
1. Claude Pro/Max Account (Recommended)
claude login
2. API Key (If supported by your Claude CLI version)
The Claude CLI may support API key authentication in some configurations. Check your Claude CLI documentation.
Important: The SDK does not handle authentication directly. If you see authentication errors, you need to authenticate using the Claude CLI first.
API Reference
Fluent API
claude(): QueryBuilder
Creates a new query builder for the fluent API.
const builder = claude()
.withModel('sonnet')
.allowTools('Read', 'Write')
.skipPermissions()
.withTimeout(30000)
.inDirectory('/path')
.withLogger(logger)
.onMessage(handler)
.withSessionId('session-id')
.query('Your prompt');
Response Parsing Methods
.asText()
- Extract plain text from assistant messages
.asJSON<T>()
- Parse JSON from the response
.asResult()
- Get the final result message
.asToolExecutions()
- Get all tool executions with results
.findToolResults(toolName)
- Find results from specific tool
.getUsage()
- Get token usage and cost statistics
.stream(callback)
- Stream messages with a callback
Classic API
query(prompt: string, options?: ClaudeCodeOptions): AsyncGenerator<Message>
Query Claude Code with a prompt and options.
Parameters
prompt
(string): The prompt to send to Claude Code
options
(ClaudeCodeOptions, optional): Configuration options
Returns
An async generator that yields Message
objects.
Types
ClaudeCodeOptions
interface ClaudeCodeOptions {
model?: string;
allowedTools?: ToolName[];
deniedTools?: ToolName[];
permissionMode?: PermissionMode;
sessionId?: string;
cwd?: string;
env?: Record<string, string>;
mcpServers?: MCPServer[];
timeout?: number;
debug?: boolean;
apiKey?: string;
baseUrl?: string;
maxTokens?: number;
temperature?: number;
tools?: ToolName[];
context?: string[];
}
Message
type Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage;
interface UserMessage {
type: 'user';
content: string;
}
interface AssistantMessage {
type: 'assistant';
content: ContentBlock[];
}
interface SystemMessage {
type: 'system';
content: string;
}
interface ResultMessage {
type: 'result';
content: string;
usage?: UsageInfo;
cost?: CostInfo;
}
ContentBlock
type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
interface TextBlock {
type: 'text';
text: string;
}
interface ToolUseBlock {
type: 'tool_use';
id: string;
name: string;
input: Record<string, unknown>;
}
interface ToolResultBlock {
type: 'tool_result';
tool_use_id: string;
content: string | Array<TextBlock | unknown>;
is_error?: boolean;
}
New Features in v0.2.0
🎯 Fluent API
A chainable API that reduces boilerplate and improves readability:
- Method chaining for configuration
- Automatic response parsing
- Built-in event handlers
- Type-safe throughout
📊 Response Parsers
Extract exactly what you need from Claude's responses:
- Text extraction with
.asText()
- JSON parsing with
.asJSON<T>()
- Tool execution analysis
- Usage statistics and costs
📝 Logging Framework
Pluggable logging system for better debugging:
- Multiple log levels (ERROR, WARN, INFO, DEBUG, TRACE)
- Console and JSON loggers included
- Custom logger support
- Multi-logger for sending to multiple destinations
Examples
Check out the examples directory for complete, runnable examples including:
- fluent-api-demo.js - Comprehensive showcase of the new fluent API
- response-parsing-demo.js - Advanced response parsing techniques
- sessions.js - Session management and conversation context
- Hello World (both classic and fluent syntax)
- File operations
- Code analysis
- Interactive sessions
- Web research
- Project scaffolding
- Error handling
For detailed documentation on the fluent API, see docs/FLUENT_API.md.
Migrating to Fluent API
The fluent API dramatically reduces boilerplate code. Here are some common migration patterns:
Before (Classic API):
let fullText = '';
for await (const message of query('Generate a story')) {
if (message.type === 'assistant') {
for (const block of message.content) {
if (block.type === 'text') {
fullText += block.text;
}
}
}
}
console.log(fullText);
After (Fluent API):
const fullText = await claude().query('Generate a story').asText();
console.log(fullText);
More migration examples in docs/FLUENT_API.md#migration-guide.
Error Handling
import { query, ClaudeSDKError, CLINotFoundError } from '@instantlyeasy/claude-code-sdk-ts';
try {
for await (const message of query('Hello')) {
console.log(message);
}
} catch (error) {
if (error instanceof CLINotFoundError) {
console.error('Please install Claude Code CLI first:');
console.error('npm install -g @anthropic-ai/claude-code');
} else if (error instanceof ClaudeSDKError) {
console.error('SDK error:', error.message);
} else if (error.message?.includes('Invalid API key')) {
console.error('Authentication required. Please run: claude login');
} else {
console.error('Unexpected error:', error);
}
}
Development
npm install
npm run build
npm test
npm run typecheck
npm run lint
Changelog
v0.2.0 (Latest) 🚀
New Features:
- ✨ Fluent API: New chainable API with
claude()
for improved developer experience
- 📊 Response Parsers: Built-in methods for extracting text, JSON, and tool results
- 📝 Logging Framework: Pluggable logging system with multiple implementations
- 🔧 Event Handlers:
onMessage()
, onAssistant()
, and onToolUse()
callbacks
- 📈 Usage Statistics: Get token counts and cost information with
.getUsage()
Improvements:
- 100% backward compatible - existing code continues to work
- Comprehensive TypeScript support throughout
- Extensive test coverage for all new features
- New examples demonstrating fluent API patterns
v0.1.4
- Include examples in npm package
v0.1.2
- Fixed CLI command search to properly find
claude
command
- Removed unsupported authentication flags (CLI handles auth internally)
- Improved error messages for authentication failures
- Updated documentation to clarify authentication flow
v0.1.1
- Added
--print
flag for non-interactive mode
- Fixed CLI path resolution
- Initial TypeScript error fixes
v0.1.0
- Initial release
- TypeScript port of official Python SDK
- Full support for Claude Code CLI features
License
MIT