claude-wire

Run Claude Code programmatically from TypeScript.

import { claude } from "@pivanov/claude-wire";

const result = await claude.ask("Fix the bug in main.ts", {
  model: "haiku",
  maxCostUsd: 0.50,
});

console.log(result.text);     // "Fixed the undefined variable..."
console.log(result.costUsd);  // 0.0084

Features

• Simple API - claude.ask() returns a typed result, claude.stream() yields events
• Structured JSON - claude.askJson(prompt, schema) with Standard Schema (Zod/Valibot/ArkType) validation
• Tool control - allow, block, or intercept any tool at runtime
• Multi-turn sessions - persistent process across multiple prompts
• Cost tracking - per-request budgets with auto-abort and projection primitives
• Typed errors - rate-limit, overload, context-length, retry-exhausted as KnownError codes
• Fully typed - discriminated union events, full IntelliSense
• Resilient - auto-respawn with backoff, transient error detection, AbortSignal
• Zero dependencies - ~9 kB minified+gzipped (bundle), ~42 kB npm tarball
• Subpath exports - /errors, /parser, /testing for narrower imports and bundle-isolated test helpers

Install

bun add @pivanov/claude-wire
# or
npm install @pivanov/claude-wire

Requires Claude Code CLI installed and authenticated. Runs on Bun >= 1.0 or Node.js >= 22.

Platform: POSIX only (macOS, Linux, WSL). Native Windows isn't supported yet -- binary resolution relies on which and POSIX path conventions.

This SDK wraps Claude Code's --output-format stream-json protocol, which is not officially documented by Anthropic and may change between releases.

CLI

claude-wire ships a minimal CLI for shell-driven JSON extraction. Same engine as claude.askJson(), no JS required.

npx @pivanov/claude-wire ask-json \
  --prompt "Extract name and age from: Alice is 30" \
  --schema '{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}}}'

Pipe the prompt via stdin and read the schema from a file:

echo "Summarize this" | npx @pivanov/claude-wire ask-json \
  --schema-file ./schema.json \
  --model haiku

Success emits a single JSON line on stdout ({ data, costUsd, tokensIn, tokensOut, tokensCacheRead, tokensCacheCreation, durationMs, sessionId }). Errors go to stderr as { error, code } with exit codes 1 (json-validation), 2 (process), 3 (budget-exceeded), 4 (invalid-args). Run npx @pivanov/claude-wire --help for the full flag list.

Documentation

Full docs, API reference, and protocol guide at pivanov.github.io/claude-wire

Try the Examples

git clone https://github.com/pivanov/claude-wire
cd claude-wire && bun install
bun run examples

Interactive menu with 9 runnable demos covering ask, askJson, streaming, sessions, tool control, cost budgets, abort, system prompts, and session resume.

Project Structure

packages/claude-wire/   the npm package
apps/docs/              VitePress documentation site
apps/examples/          interactive example runner

Development

bun install
bun run test        # 330 tests including parser fuzz
bun run typecheck
bun run lint
bun run docs:dev    # local docs server
bun run examples    # try the examples

Sponsors

Supported by LogicStar AI

License

MIT