BatonJS

A TypeScript-based workflow script runner for coding agents.

Why BatonJS?

A TypeScript-based workflow script runner for coding agents. Write plain async/await scripts with a small set of injected globals — the engine handles concurrency, retries, budget tracking, and SDK orchestration.

• SDK-agnostic — Pluggable adapters for Anthropic Claude, Tencent CodeBuddy, OpenAI Codex, and Reasonix. Swap providers without rewriting workflow logic.

• Zero boilerplate — agent(), parallel(), pipeline(), phase(), log(), and budget are all you need. No class inheritance, decorators, or DSL.

• Automatic concurrency & throttling — parallel([...]) handles hundreds of items with automatic semaphore management.

• Built-in budget tracking — Every agent() call deducts from a shared pool; loops exit automatically when budget is exhausted.

• Retry, structured output, sub-workflows — Exponential backoff for transient failures, JSON Schema validation for typed results, and nested workflow composition — all out of the box.

Quick Start

Prerequisites: Node.js ≥ 18

Install:

npm install batonjs

Or run directly without installing:

npx -y batonjs ./workflow.js

Write a workflow script:

// workflow.js
export const meta = {
  name: 'my-first-workflow',
  phases: [{ title: 'Analyze' }, { title: 'Summarize' }],
}

// Phase 1: Run two agents in parallel
phase('Analyze')
const [security, perf] = await parallel([
  () => agent('Check this code for security issues', { label: 'security' }),
  () => agent('Check this code for performance bottlenecks', { label: 'perf' }),
])

// Phase 2: Summarize findings
phase('Summarize')
const summary = await agent(
  `Summarize these findings:\n${JSON.stringify({ security, perf })}`,
  { label: 'summarize' },
)

log('Done!')
return { summary }

Run it:

batonjs ./workflow.js

Switch to a different SDK backend:

batonjs --sdk codex ./workflow.js
batonjs --sdk codebuddy ./workflow.js
batonjs --sdk reasonix ./workflow.js

CLI Reference

batonjs [options] <script>

| Flag | Description | Default | |------|-------------|---------| | --args <json> | Pass arguments into the script as the args global | — | | --budget <usd> | Max spend in USD | unlimited | | --concurrency <n> | Max concurrent agents | 2 | | --cwd <dir> | Working directory for agents | . | | --sdk <name> | claude, codebuddy, codex, or reasonix | claude | | --timeout <minutes> | Per-agent timeout in minutes | 5 | | -h, --help | Show help | — |

Script API

Workflow scripts receive these injected globals:

| Global | Description | |--------|-------------| | agent(prompt, opts?) | Run an AI agent. Returns the result or null on failure | | parallel(thunks) | Run an array of async thunks concurrently; waits for all | | pipeline(items, ...stages) | Stream each item through stages independently | | phase(title) | Mark the current phase (for progress display) | | log(message) | Emit a log message | | budget | { total, spent(), remaining() } — real-time budget info | | args | Custom arguments passed via --args | | workflow(ref, args?) | Run a nested sub-workflow (one level max) |

agent(prompt, opts?)

// Free-text response
const result = await agent('Explain this error')

// Structured output with JSON Schema
const issues = await agent('Find bugs in this code', {
  schema: {
    type: 'object',
    properties: { bugs: { type: 'array', items: { type: 'string' } } },
    required: ['bugs'],
  },
})
// issues.bugs — validated array of strings

Options:

| Option | Description | |--------|-------------| | label | Display name for progress output | | phase | Assign to a phase group | | schema | JSON Schema for structured output | | model | Override model for this agent |

Examples

The examples/ directory contains 31 ready-to-run workflows, organized by level:

| # | Pattern | Description | |---|---------|-------------| | 01 | agent() | Hello World — one agent, one result | | 06 | schema | Structured output with JSON Schema validation | | 07–08 | parallel / pipeline | Concurrency primitives | | 09 | pipeline vs parallel | When to use which | | 11 | Multi-stage pipeline | Chain stages per item | | 12 | Loop-until-dry | Keep discovering until exhausted | | 13 | Loop-until-budget | Scale depth to budget | | 15 | Adversarial verify | N skeptics try to refute a claim | | 16 | Judge panel | Diverse approaches scored and synthesized | | 21 | Code review | Multi-dimension review with verification | | 31 | README generator | Five-dimension README generation |

Run any example:

batonjs ./examples/01-hello-world.js
batonjs --sdk codex ./examples/06-structured-output.js
batonjs --budget 2.0 ./examples/21-code-review.js

Programmatic API

import { Engine } from 'batonjs'

const engine = new Engine({
  scriptPath: './workflow.js',
  sdk: 'claude',       // or 'codebuddy', 'codex', or 'reasonix'
  maxBudgetUsd: 2.0,
  maxConcurrency: 5,
})

engine.on((event) => {
  if (event.kind === 'log') console.log(event.message)
})

const result = await engine.run()

if (result.ok) {
  console.log('Result:', result.value.result)
  console.log('Cost: $' + result.value.totalCostUsd.toFixed(4))
}

API Reference

BatonJS exposes a compact public surface — engine, result helpers, SDK adapters, and a rich set of types. Everything below is re-exported from the entry point.

Engine

The workflow runtime that loads a script, injects globals, and orchestrates execution.

| Export | Description | |--------|-------------| | Engine | Load a script and run it inside a sandboxed workflow environment. | | EngineOptions | Configuration for new Engine(): scriptPath, args, maxBudgetUsd, maxConcurrency, cwd, permissionMode, sdk, agentTimeoutMs, signal. | | EngineRunResult | Return type of engine.run() — always a Result<EngineResult, Error>. | | EngineResult | Successful run payload: { success, result, totalCostUsd, durationMs, meta }. |

import { Engine } from "batonjs";
const engine = new Engine({ scriptPath: "./my-workflow.ts", maxBudgetUsd: 5.0 });
const outcome = await engine.run(); // Result<EngineResult, Error>

→ Quick Start · Events

Result Helpers

Predictable, allocation-friendly error handling without try/catch.

| Export | Description | |--------|-------------| | ok | Create a successful Result<T, E> value. | | err | Create a failed Result<T, E> error. | | Result | Discriminated union: { ok: true; value: T } \| { ok: false; error: E }. |

import { ok, err } from "batonjs";
const found = ok(42);          // Result<number, never>
const failed = err("missing"); // Result<never, string>

→ TypeScript Philosophy

SDK Adapters

Pluggable backends that translate BatonJS calls into provider-specific SDK operations.

| Export | Description | |--------|-------------| | createSdkProvider | Factory — returns an SdkProvider for a given backend name. | | SdkName | Union: 'claude' \| 'codebuddy' \| 'codex' \| 'reasonix'. | | SdkProvider | Contract: { query(options): SdkQueryHandle }. | | SdkQueryOptions | Options for a query call: permissionMode, abortController, outputFormat, model, cwd, maxBudgetUsd, effort. | | SdkQueryHandle | Async-iterable handle with interrupt() and return() cleanup. | | SdkResultMessage | Normalised result message, discriminated on subtype: 'success' vs error variants. | | EffortLevel | Unified reasoning effort: 'medium' \| 'high' \| 'xhigh'. |

import { createSdkProvider } from "batonjs";
const sdk = createSdkProvider("claude");
const handle = sdk.query({ model: "claude-sonnet-4-20250514", permissionMode: "auto" });

→ SDK Adapters source

Events

Synchronous, type-safe event bus for observing engine lifecycle.

| Export | Description | |--------|-------------| | EngineEventBus | Create a bus, register handlers, and emit typed events. | | EngineEvent | Discriminated union of all lifecycle events (workflow_start, workflow_end, phase, log, agent_start, agent_end, agent_error, budget_update, …). | | EngineEventHandler | Handler signature: (event: EngineEvent) => void. |

import { EngineEventBus } from "batonjs";
const bus = new EngineEventBus();
bus.on("agent_start", (e) => console.log(`→ ${e.label}`));

→ Engine Events types

Script Globals

The runtime contract injected into every workflow script.

| Export | Description | |--------|-------------| | ScriptGlobals | Full set: agent, parallel, pipeline, phase, log, budget, args, workflow. | | ScriptMeta | Shape of export const meta = { name, description, phases }. | | AgentOpts | Options for agent(): label, phase, schema, model, maxRetries, effort. | | BudgetHandle | Script-facing budget: { total, spent(), remaining() }. | | WorkflowRef | Reference to another workflow: string or { scriptPath }. |

// Inside a workflow script — globals are injected by the Engine
const result = await agent("Summarise the article", { schema: SummarySchema });
const all = await parallel([() => agent("A"), () => agent("B")]);

→ Script Globals types · Examples

Concurrency & Budget

Utilities for controlling parallelism and spending.

| Export | Description | |--------|-------------| | Semaphore | Counting semaphore — acquire() / release() to cap concurrency. | | BudgetTracker | Track cumulative USD spend — record(), tryAcquire(), adjust(). |

import { Semaphore, BudgetTracker } from "batonjs";
const sem = new Semaphore(4);
const budget = new BudgetTracker(10.0); // $10 USD cap

SDK Backends

| Backend | --sdk value | Package | |---------|--------------|---------| | Anthropic Claude | claude (default) | @anthropic-ai/claude-agent-sdk | | Tencent CodeBuddy | codebuddy | @tencent-ai/agent-sdk | | OpenAI Codex | codex | @openai/codex-sdk | | Reasonix | reasonix | CLI binary (reasonix run) |

Documentation & Resources

Guides

• Getting Started — Installation, quick start, and basic usage of the BatonJS workflow engine
• Workflow Tutorial — Step-by-step tutorial for AI assistants to learn BatonJS concepts, API patterns, and best practices (6 chapters)
• Examples — 31 workflow examples from hello-world to full quality gate, covering pipeline, parallel, adversarial verify, judge panel, and more

API Reference

• API Entry Point — Public API: Engine class, Result type, SDK provider, event bus, concurrency primitives, budget tracker
• CLI Reference — Command-line interface options: --args, --budget, --concurrency, --cwd, --sdk, --timeout
• Script Globals — Workflow script globals: agent(), parallel(), pipeline(), phase(), log(), budget, args, workflow()
• Engine Events — Discriminated union event types emitted during workflow execution for observability
• SDK Adapters — Pluggable SDK backends: Anthropic Claude Agent SDK, Tencent Codebuddy Agent SDK, OpenAI Codex SDK, Reasonix

Development

• TypeScript Philosophy — Project coding conventions: zero any, discriminated unions, Result pattern, never exhaustiveness checks
• Contributing — Development commands (dev, build, test, lint, check) and project setup with husky + lint-staged

Project

• Changelog — Release history and version changes
• GitHub Repository — Source code, issues, and pull requests

Contributing

Contributions are welcome! To get started:

• Bug reports — Open an issue with a minimal reproduction.
• Feature requests — Open an issue with a clear use case.
• Pull requests — Fork the repo, create a branch, and submit a PR. Please ensure npm run check passes before submitting.

License

This project is licensed under the MIT license.