Claude-Code-SDK-Ts

4 hours ago 1

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.

npm install @instantlyeasy/claude-code-sdk-ts # or yarn add @instantlyeasy/claude-code-sdk-ts # or pnpm add @instantlyeasy/claude-code-sdk-ts

Prerequisites:

Node.js 18 or later
Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)

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'; // Simple Hello World const response = await claude() .withModel('sonnet') .skipPermissions() .query('Say "Hello World!"') .asText(); console.log(response); // Outputs: Hello World!

File Operations with Fluent API

import { claude } from '@instantlyeasy/claude-code-sdk-ts'; // Create a file with automatic result extraction const result = await claude() .allowTools('Write') .skipPermissions() .query('Create a hello.txt file with "Hello from Claude!"') .asResult(); console.log('Task completed:', result); // Read and parse JSON data const config = await claude() .allowTools('Read') .query('Read package.json and return its content') .asJSON(); console.log('Version:', config.version);

import { claude, ConsoleLogger, LogLevel } from '@instantlyeasy/claude-code-sdk-ts'; // Full example with logging, event handlers, and response parsing 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(); // Get detailed tool execution results 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'; // Simple Hello World 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); // Outputs: Hello World! } } } }

This SDK delegates all authentication to the Claude CLI. There are two ways to authenticate:

1. Claude Pro/Max Account (Recommended)

# One-time setup - login with your Claude account 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.

Creates a new query builder for the fluent API.

const builder = claude() .withModel('sonnet') // Set model .allowTools('Read', 'Write') // Configure tools .skipPermissions() // Skip permission prompts .withTimeout(30000) // Set timeout .inDirectory('/path') // Set working directory .withLogger(logger) // Add logging .onMessage(handler) // Add event handlers .query('Your prompt'); // Execute query

.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

query(prompt: string, options?: ClaudeCodeOptions): AsyncGenerator<Message>

Query Claude Code with a prompt and options.

prompt (string): The prompt to send to Claude Code
options (ClaudeCodeOptions, optional): Configuration options

An async generator that yields Message objects.

interface ClaudeCodeOptions { // Model selection model?: string; // Claude model to use (e.g., 'opus', 'sonnet') // Tool configuration allowedTools?: ToolName[]; // Explicitly allowed tools deniedTools?: ToolName[]; // Explicitly denied tools // Permission handling permissionMode?: PermissionMode; // 'default' | 'acceptEdits' | 'bypassPermissions' // Execution environment cwd?: string; // Working directory env?: Record<string, string>; // Environment variables // MCP (Model Context Protocol) servers mcpServers?: MCPServer[]; // MCP servers to connect // SDK options timeout?: number; // Timeout in milliseconds debug?: boolean; // Enable debug logging (Note: may interfere with JSON parsing) // Deprecated options (not used by CLI transport) apiKey?: string; // Use `claude login` instead baseUrl?: string; // Not applicable for CLI maxTokens?: number; // Not configurable via CLI temperature?: number; // Not configurable via CLI tools?: ToolName[]; // Use allowedTools/deniedTools instead context?: string[]; // Not implemented }

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; }

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; }

A chainable API that reduces boilerplate and improves readability:

Method chaining for configuration
Automatic response parsing
Built-in event handlers
Type-safe throughout

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

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

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
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.

The fluent API dramatically reduces boilerplate code. Here are some common migration patterns:

const fullText = await claude() .query('Generate a story') .asText(); console.log(fullText);

More migration examples in docs/FLUENT_API.md#migration-guide.

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); } }

# Install dependencies npm install # Build the SDK npm run build # Run tests npm test # Type checking npm run typecheck # Linting npm run lint

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: