claude-code-executor

A TypeScript library for executing Claude Code sessions programmatically.

Features

• ✅ Simple API - One function to execute Claude Code sessions
• ✅ Type-safe - Full TypeScript support with type inference
• ✅ Timeout handling - Graceful process termination (SIGTERM → SIGKILL)
• ✅ Error handling - Always returns a result, never throws
• ✅ Extensible - Support for all Claude Code CLI options

Requirements

• Bun runtime
• Claude Code CLI (claude) installed and authenticated

Installation

bun add claude-code-executor

Usage

Basic Example

import { execute } from 'claude-code-executor';

const result = await execute('Create a simple web server');

if (result.success) {
  console.log(
    `Success! Cost: $${result.costUsd}, Duration: ${result.durationMs}ms`,
  );
} else {
  console.error(`Failed: ${result.error}`);
}

With Options

import { execute } from 'claude-code-executor';

const result = await execute('Create a simple web server', {
  cwd: '/path/to/project',
  model: 'sonnet',
  timeout: 300000, // 5 minutes
  permissions: 'dangerously-skip-permissions',
  env: { MY_VAR: 'value' },
  extraFlags: ['--some-flag'],
});

API Reference

execute(prompt, options?)

Execute a Claude Code session.

Parameters:

• prompt: string - The prompt to send to Claude Code
• options?: ExecuteOptions - Optional execution options

Returns: Promise<ExecutionResult>

ExecuteOptions

type ExecuteOptions = {
  cwd?: string; // Working directory (default: process.cwd())
  model?: 'sonnet' | 'opus' | 'haiku' | string; // Claude model (default: "sonnet")
  timeout?: number; // Timeout in ms (default: 300000)
  permissions?: string; // Permission mode (default: "dangerously-skip-permissions")
  env?: Record<string, string>; // Environment variables
  extraFlags?: string[]; // Additional CLI flags
};

ExecutionResult

type ExecutionResult = {
  success: boolean; // Whether execution succeeded
  costUsd: number; // Cost in USD
  durationMs: number; // Duration in milliseconds
  error?: string; // Error message (when success=false)
  rawOutput?: string; // Raw stdout (for debugging)
};

Error Handling

The library never throws exceptions. All errors are returned as ExecutionResult with success: false:

• Timeout: error: "Timed out after Xms"
• JSON Parse Error: error: "Failed to parse JSON output: ..."
• Claude Code Error: error: "subtype: ..."
• Process Spawn Error: error: "Failed to spawn process: ..."

License

MIT