What Is Spawner?

A single async iterable API to drive Claude Code, Codex CLI, OpenCode, and pi programmatically:

1. You pass SpawnOptions to spawn().
2. You iterate typed CliEvent objects as they stream in (text, tool use, tool result, errors).
3. You get back a structured CliResult -- same shape regardless of which CLI you chose.

It handles process spawning, JSONL stream parsing, session management, error classification, and CLI detection so you can build orchestrators, CI pipelines, and editor integrations without writing per-CLI adapters.

ESM only. Zero runtime dependencies. TypeScript-first.

Used by looper as its CLI driver.

Quick Start

import { spawn } from '@0xtiby/spawner';

const proc = spawn({
  cli: 'claude',
  prompt: 'Refactor the utils module to use named exports',
  cwd: '/path/to/project',
});

for await (const event of proc.events) {
  switch (event.type) {
    case 'text':
      console.log(event.content);
      break;
    case 'tool_use':
      console.log(`Using tool: ${event.tool?.name}`);
      break;
    case 'error':
      console.error(event.content);
      break;
    case 'done':
      console.log('Session:', event.result?.sessionId);
      console.log('Tokens:', event.result?.usage?.totalTokens);
      break;
  }
}

Installation

pnpm add @0xtiby/spawner
# or: npm install @0xtiby/spawner

Prerequisites: Node.js 18+ and at least one supported CLI installed and authenticated:

• Claude Code (claude)
• Codex CLI (codex)
• OpenCode (opencode)
• pi (pi)

CLI Feature Parity

Not every CLI supports every SpawnOptions field. This table shows what each adapter passes through and what it silently ignores.

| Feature | Claude | Codex | OpenCode | pi | |---|---|---|---|---| | model | Yes | Yes | Yes | Yes | | sessionId | Yes | Yes | Yes | Yes | | continueSession | Yes | Yes | Yes | Yes | | forkSession | Yes | Yes | Yes | Yes | | autoApprove | Yes | Yes | -- | No-op | | effort | Yes | Yes | -- | Yes | | addDirs | Yes | Yes | -- | -- | | ephemeral | Yes | Yes | -- | Yes | | allowInteractiveTools | Yes | -- | -- | -- | | extraArgs | Yes | Yes | Yes | Yes |

Legend: "Yes" = passed to the CLI. "--" = silently ignored. "No-op" = accepted but has no effect (the CLI is already non-interactive).

Pi-specific notes

• autoApprove is a no-op: pi --mode json is already a headless print mode with no approval prompts.
• addDirs and allowInteractiveTools are silently ignored so existing SpawnOptions work without crashing.
• effort is mapped to --thinking <level>. Pi accepts off, minimal, low, medium, high, xhigh natively, so all values pass through; max collapses to xhigh.
• detect() reports authenticated: true whenever the pi binary exists. Pi resolves credentials per provider at runtime (env vars, config file), so this signal is non-authoritative — real auth failures surface via classifyError when you actually spawn.

Core Concepts

Streaming Events

spawn() returns a CliProcess whose events property is an AsyncIterable<CliEvent>. Each event carries a type field that tells you what happened. Iterate with for await...of to process events as they stream in.

| Type | When It Fires | Key Fields | |---|---|---| | text | The CLI emits a chunk of assistant text | content | | tool_use | The CLI invokes a tool | tool.name, tool.input | | tool_result | A tool call completes | toolResult.name, toolResult.output, toolResult.error | | error | The CLI reports an inline error | content | | system | Internal lifecycle signals (session start, step boundaries) | content | | done | The process exits | result (contains CliResult) |

Every event also includes timestamp (Unix ms) and raw (the original JSONL line).

Session Management

Use these SpawnOptions fields to control session behavior:

| Goal | Options to Set | |---|---| | Start a new session | (none -- this is the default) | | Resume a session by ID | sessionId: '<id>' | | Resume the most recent session | continueSession: true | | Fork from a specific session | sessionId: '<id>', forkSession: true | | Fork from the most recent session | continueSession: true, forkSession: true |

forkSession is additive -- it only takes effect when you also set sessionId or continueSession. A fork creates a new session branched from the specified point, leaving the original session unchanged.

Error Classification

When a CLI process exits with a non-zero code, spawner runs the output through classifyError() and attaches a structured CliError to the result. Each error has a code, a human-readable message, a retryable flag, and an optional retryAfterMs hint. You can use the retryable flag to build automatic retry logic. See the Error Codes section for the full list.

Usage

Spawn a Process

spawn() is the main entry point. It returns a CliProcess with an async iterable of events and a promise that resolves when the process exits.

import { spawn } from '@0xtiby/spawner';

const proc = spawn({
  cli: 'codex',
  prompt: 'Add input validation to the signup handler',
  cwd: '/path/to/repo',
  model: 'o4-mini',
  autoApprove: true,
});

// Stream events as they arrive
for await (const event of proc.events) {
  if (event.type === 'text') {
    process.stdout.write(event.content ?? '');
  }
}

// Or just await the final result
const result = await proc.done;

Resume or Fork a Session

Pass sessionId to continue a previous conversation, or combine it with forkSession to branch off:

// Resume an existing session
const proc = spawn({
  cli: 'claude',
  prompt: 'Now add tests for the changes you just made',
  cwd: '/path/to/repo',
  sessionId: previousResult.sessionId!,
});

// Fork from an existing session (creates a new branch)
const forked = spawn({
  cli: 'claude',
  prompt: 'Try a different approach to the refactor',
  cwd: '/path/to/repo',
  sessionId: previousResult.sessionId!,
  forkSession: true,
});

// Resume the most recent session (no ID needed)
const continued = spawn({
  cli: 'claude',
  prompt: 'What was I working on?',
  cwd: '/path/to/repo',
  continueSession: true,
});

Cancel or Interrupt

Use AbortSignal for external cancellation, or call interrupt() for a graceful shutdown:

const controller = new AbortController();

const proc = spawn({
  cli: 'claude',
  prompt: 'Perform a large refactor',
  cwd: '/path/to/repo',
  abortSignal: controller.signal,
});

// Cancel after 30 seconds
setTimeout(() => controller.abort(), 30_000);

// Or interrupt gracefully (SIGTERM, then SIGKILL after grace period)
const result = await proc.interrupt(5000); // 5s grace period (default)

Detect Installed CLIs

import { detect, detectAll } from '@0xtiby/spawner';

// Check a single CLI
const claude = await detect('claude');
// { installed: true, version: '1.2.3', authenticated: true, binaryPath: '/usr/local/bin/claude' }

// Check all CLIs concurrently
const all = await detectAll();
// { claude: DetectResult, codex: DetectResult, opencode: DetectResult }

Extract Results from Raw Output

If you have captured JSONL output from a previous CLI run, parse it without spawning a process:

import { extract } from '@0xtiby/spawner';

const result = extract({
  cli: 'claude',
  rawOutput: capturedJsonlString,
});

console.log(result.sessionId);
console.log(result.usage);

Query the Model Registry

Models are fetched dynamically from models.dev and cached for 24 hours.

import { listModels, getKnownModels, refreshModels } from '@0xtiby/spawner';

// All models from all providers
const all = await listModels();

// Models for a specific CLI
const claudeModels = await getKnownModels('claude');

// Filter by provider
const openaiModels = await listModels({ provider: 'openai' });

// With offline fallback
const models = await listModels({
  cli: 'claude',
  fallback: [{ id: 'claude-sonnet-4-20250514', name: 'Claude Sonnet 4', provider: 'anthropic', contextWindow: 200_000, supportsEffort: true }],
});

// Force-refresh the cache
await refreshModels();

API Reference

spawn(options: SpawnOptions): CliProcess

Spawns a CLI process and returns a handle for streaming events and awaiting the result.

SpawnOptions

| Option | Type | Default | Description | |---|---|---|---| | cli | CliName | required | Which CLI to spawn: 'claude', 'codex', 'opencode', or 'pi' | | prompt | string | required | The prompt to send to the CLI | | cwd | string | required | Working directory for the process | | model | string | CLI default | Model identifier to use | | sessionId | string | -- | Resume an existing session | | effort | 'off' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'max' \| 'xhigh' | -- | Effort/reasoning level (supported by some models) | | autoApprove | boolean | -- | Skip tool confirmation prompts. Maps to full permission/sandbox bypass on claude (--dangerously-skip-permissions) and codex (--dangerously-bypass-approvals-and-sandbox). No effect on opencode. | | forkSession | boolean | -- | Fork from an existing session | | continueSession | boolean | -- | Continue the most recent session | | addDirs | string[] | -- | Additional directories to include | | ephemeral | boolean | -- | Run without persisting session | | verbose | boolean | -- | Enable debug logging to stderr | | allowInteractiveTools | boolean | -- | Allow tools that prompt the user for input (Claude only) | | abortSignal | AbortSignal | -- | Signal to abort the process | | extraArgs | string[] | -- | Additional CLI arguments passed through |

CliProcess

| Property / Method | Type | Description | |---|---|---| | events | AsyncIterable<CliEvent> | Stream of parsed events | | pid | number | OS process ID | | interrupt(graceMs?) | (graceMs?: number) => Promise<CliResult> | Gracefully stop the process (SIGTERM, then SIGKILL after graceMs) | | done | Promise<CliResult> | Resolves when the process exits |

CliEvent

| Field | Type | Description | |---|---|---| | type | CliEventType | 'text', 'tool_use', 'tool_result', 'error', 'system', or 'done' | | timestamp | number | Unix timestamp (ms) | | content | string? | Text content (for text, error, system events) | | tool | { name: string; input?: Record<string, unknown> }? | Tool invocation details (for tool_use events) | | toolResult | { name: string; output?: string; error?: string }? | Tool result (for tool_result events) | | result | CliResult? | Final result (only on done events) | | raw | string | Original JSONL line |

CliResult

| Field | Type | Description | |---|---|---| | exitCode | number | Process exit code | | sessionId | string \| null | Session ID for resumption | | usage | TokenUsage \| null | Token usage and cost | | model | string \| null | Model that was used | | error | CliError \| null | Structured error (if non-zero exit) | | durationMs | number | Wall-clock duration in milliseconds |

TokenUsage

| Field | Type | |---|---| | inputTokens | number \| null | | outputTokens | number \| null | | totalTokens | number \| null | | cost | number \| null |

detect(cli: CliName): Promise<DetectResult>

Checks whether a CLI is installed, its version, and authentication status.

detectAll(): Promise<Record<CliName, DetectResult>>

Runs detect() for all four CLIs concurrently.

extract(options: ExtractOptions): CliResult

Parses captured JSONL output into a CliResult without spawning a process. Useful for processing saved output or testing.

classifyError(cli, exitCode, stderr, stdout): CliError

Classifies raw process output into a structured CliError using CLI-specific adapters.

classifyErrorDefault(exitCode, stderr, stdout): CliError

Default error classifier using shared pattern matching. Useful for building custom adapters.

matchSharedPatterns(stderr, stdout)

Low-level pattern matching against the shared error pattern table. Returns { code, retryable, matchedLine } or null.

parseRetryAfterMs(text): number

Extracts a retry-after duration (in ms) from error text. Returns 60000 as a default fallback.

listModels(options?: ListModelsOptions): Promise<KnownModel[]>

Returns models fetched from models.dev, filtered by CLI and/or provider. Results are sorted alphabetically by id. When both cli and provider are set, provider takes precedence.

getKnownModels(cli?: CliName, fallback?: KnownModel[]): Promise<KnownModel[]>

Convenience wrapper over listModels(). Returns models optionally filtered by CLI, with optional fallback on fetch failure.

refreshModels(): Promise<void>

Force-refreshes the in-memory model cache from models.dev. On failure, the existing cache is preserved.

Error Codes

Spawner classifies CLI errors into typed error codes so you can handle them programmatically:

| Error Code | Retryable | Description | |---|---|---| | rate_limit | Yes | Rate limited or overloaded -- check retryAfterMs | | auth | No | Not authenticated or invalid credentials | | session_not_found | No | Session ID does not exist | | model_not_found | No | Specified model is invalid | | context_overflow | No | Input exceeds model context window | | permission_denied | No | Tool use requires confirmation | | binary_not_found | No | CLI binary not found on PATH | | fatal | No | Non-recoverable process error | | unknown | No | Unrecognized error |

Retry Example

import { spawn, type CliResult } from '@0xtiby/spawner';

async function spawnWithRetry(options: Parameters<typeof spawn>[0], maxRetries = 3): Promise<CliResult> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const proc = spawn(options);
    const result = await proc.done;

    if (!result.error?.retryable || attempt === maxRetries) {
      return result;
    }

    const delay = result.error.retryAfterMs ?? 60_000;
    console.log(`Rate limited, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`);
    await new Promise((r) => setTimeout(r, delay));
  }

  throw new Error('unreachable');
}

Models

Models are fetched dynamically from models.dev and cached in memory for 24 hours. There is no static model list -- call listModels() or getKnownModels() to get the current catalog. Use refreshModels() to force a cache refresh.

Architecture

Spawner uses an adapter pattern to normalize differences between CLIs. Each CLI has an adapter that implements:

• buildCommand() -- Translates SpawnOptions into binary name, arguments, and optional stdin
• parseLine() -- Parses a JSONL line into normalized CliEvent objects
• detect() -- Checks installation and authentication
• classifyError() -- CLI-specific error classification with fallback to shared patterns

The spawn() function orchestrates the full lifecycle: adapter selection, child process spawning, readline-based stream parsing, event queuing via async iterable, accumulator tracking (session ID, token usage, model), and result construction on exit.

Examples

Interactive Chat TUI

examples/chat.ts is a fully working terminal chat app built on spawner. It auto-detects installed CLIs, lets you pick one, then drops you into a streaming chat loop with session continuity.

pnpm tsx examples/chat.ts

Features:

• CLI selection -- detects installed CLIs, shows versions and auth status, prompts you to pick one
• Streaming responses -- text streams to stdout in real-time with colored labels
• Tool-use indicators -- shows which tools the CLI invokes during a response
• Session continuity -- captures sessionId so follow-up messages continue the conversation
• Ctrl+C interrupt -- interrupts a streaming response without killing the app
• Slash commands -- /exit to quit, /new to start a fresh session with a different CLI
• Error handling -- rate limits, auth failures, and CLI crashes are caught and displayed cleanly

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests (334 tests across 20 files)
pnpm test

# Type-check without emitting
pnpm lint

License

MIT