Skip to main content

​
Prerequisites

  • Bun >= 1.3 — Smithers uses Bun’s native SQLite driver and runtime APIs. Install from bun.sh.
  • TypeScript >= 5 — Required as a peer dependency.

​
Install

bun add smithers-orchestrator ai @ai-sdk/anthropic zod
This installs:
PackagePurpose
smithers-orchestratorCore framework: components, engine, CLI, JSX runtime
aiVercel AI SDK — provides the ToolLoopAgent class and model abstractions
@ai-sdk/anthropicAnthropic provider for Claude models (swap for any Vercel AI SDK provider)
zodSchema validation for task outputs (v4)
The following dependencies are bundled with smithers-orchestrator and do not need to be installed separately:
  • react and react-reconciler — used internally by the JSX renderer
  • drizzle-orm — used internally for SQLite database access
  • drizzle-zod — used internally for Zod-to-Drizzle schema conversion

​
Optional: JJ (Jujutsu) for Revert Support

Smithers can record VCS snapshots at each task completion and revert filesystem changes when a task is re-run. This requires Jujutsu, a Git-compatible VCS: 
brew install jj
If JJ is not installed, revert functionality is unavailable and JJ pointers are recorded as null in the database. Everything else works normally.

​
Project Setup

Create a new project from scratch: 
mkdir my-workflow && cd my-workflow
bun init -y
bun add smithers-orchestrator ai @ai-sdk/anthropic zod
Set your API key: 
export ANTHROPIC_API_KEY="sk-ant-..."

​
TypeScript Configuration

Smithers provides its own JSX runtime. Configure your tsconfig.json to use it: 
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true
  }
}
The key setting is "jsxImportSource": "smithers-orchestrator", which tells TypeScript to resolve JSX element creation from smithers-orchestrator/jsx-runtime instead of the default React runtime. Alternatively, you can use "jsxImportSource": "react" if you prefer — Smithers components work with the standard React JSX runtime as well. You can also set the import source per-file with a pragma comment: 
/** @jsxImportSource smithers-orchestrator */

​
Verify Installation

Create a minimal workflow.tsx to confirm everything is wired up: 
import { createSmithers, Task, runWorkflow } from "smithers-orchestrator";
import { ToolLoopAgent as Agent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

const { Workflow, smithers } = createSmithers({
  greeting: z.object({ message: z.string() }),
});

const greeter = new Agent({
  model: anthropic("claude-sonnet-4-20250514"),
  instructions: "You are friendly. Return JSON with a 'message' field.",
});

const workflow = smithers((ctx) => (
  <Workflow name="hello">
    <Task id="greet" output="greeting" agent={greeter}>
      Say hello to the user
    </Task>
  </Workflow>
));

const result = await runWorkflow(workflow, {
  input: {},
});

console.log(result);

bun run workflow.tsx
If you see { runId: "...", status: "finished", output: [...] }, your installation is working.

​
Next Steps

  • Quickstart — Build a multi-step workflow with sequential tasks.
  • Introduction — Overview of Smithers concepts and architecture.