Skip to main content

​
Quick Start

Let your agent write agents. This guide gets you running in 2 minutes.

​
Prerequisites

Bun is required. Smithers uses Bun-specific features (bun:sqlite, Bun.spawn). Node.js is not currently supported.
RequirementVersionInstall
Bun1.0+curl -fsSL https://bun.sh/install | bash
Claude Codelatestbun install -g @anthropic-ai/claude-code
Git2.0+Pre-installed on most systems
Optional:
ToolPurpose
Jujutsu (jj)Better VCS snapshot support
Smithers uses Claude Code’s subscription for API access - no separate Anthropic API key needed.

​
Installation

bun add smithers-orchestrator

​
Canonical Workflow

Create my-workflow.tsx: 
#!/usr/bin/env bun

import {
  createSmithersRoot,
  createSmithersDB,
  SmithersProvider,
  Phase,
  Step,
  Claude,
} from "smithers-orchestrator";

// 1. Create database for state persistence
const db = await createSmithersDB({ path: ".smithers/my-workflow" });

// 2. Start or resume execution
let executionId: string;
const incomplete = await db.execution.findIncomplete();
if (incomplete) {
  executionId = incomplete.id;
  console.log("Resuming:", executionId);
} else {
  executionId = await db.execution.start("My Workflow", "my-workflow.tsx");
}

// 3. Define workflow with Phase/Step/Claude composition
function Workflow() {
  return (
    <SmithersProvider db={db} executionId={executionId} maxIterations={10}>
      <Phase name="Research">
        <Step name="Analyze codebase">
          <Claude model="sonnet">
            Analyze this codebase structure and identify patterns.
          </Claude>
        </Step>
        <Step name="Document findings">
          <Claude model="sonnet">
            Document the key patterns found in the previous analysis.
          </Claude>
        </Step>
      </Phase>

      <Phase name="Implementation">
        <Step name="Write code">
          <Claude model="sonnet">
            Implement improvements based on the research phase.
          </Claude>
        </Step>
        <Step name="Write tests">
          <Claude model="sonnet">
            Write tests for the new implementation.
          </Claude>
        </Step>
      </Phase>

      <Phase name="Review">
        <Step name="Review changes">
          <Claude model="sonnet">
            Review all changes and ensure quality standards are met.
          </Claude>
        </Step>
      </Phase>
    </SmithersProvider>
  );
}

// 4. Mount and run orchestrator
const root = createSmithersRoot();
await root.mount(Workflow);

// 5. Complete and close
await db.execution.complete(executionId);
await db.close();

​
Run

bun my-workflow.tsx

​
Understanding the Code

1

Create Database

const db = await createSmithersDB({ path: ".smithers/my-workflow" });
SQLite database persists all state, enabling resume on crash/restart.
2

Start/Resume Execution

const incomplete = await db.execution.findIncomplete();
if (incomplete) {
  executionId = incomplete.id;
} else {
  executionId = await db.execution.start("My Workflow", "my-workflow.tsx");
}
Automatically resumes incomplete executions.
3

SmithersProvider

<SmithersProvider db={db} executionId={executionId} maxIterations={10}>
Provides database and orchestration context to all children.
4

Phase/Step/Claude Composition

<Phase name="Research">
  <Step name="Analyze">
    <Claude model="sonnet">Prompt here</Claude>
  </Step>
</Phase>
  • Phase: Sequential workflow stages (only active phase executes)
  • Step: Sequential tasks within a phase
  • Claude: AI agent execution
5

Mount with createSmithersRoot

const root = createSmithersRoot();
await root.mount(Workflow);
React reconciler mounts and executes the component tree.
6

Close Database

await db.execution.complete(executionId);
await db.close();
Mark complete and flush writes.

​
Minimal Example

For simple single-agent tasks: 
#!/usr/bin/env bun

import {
  createSmithersRoot,
  createSmithersDB,
  SmithersProvider,
  Claude,
} from "smithers-orchestrator";

const db = await createSmithersDB({ path: ".smithers/simple" });
const executionId = await db.execution.start("Simple", "simple.tsx");

function Workflow() {
  return (
    <SmithersProvider db={db} executionId={executionId}>
      <Claude model="sonnet" onFinished={(r) => console.log(r.output)}>
        Analyze this codebase and suggest three improvements.
      </Claude>
    </SmithersProvider>
  );
}

const root = createSmithersRoot();
await root.mount(Workflow);
await db.close();

​
Let Claude Write It

The real power: you don’t have to write Smithers yourself. Describe what you want: 
User: "Create a workflow that monitors my CI, fixes failures automatically,
       and escalates after 3 failed attempts"

Claude: *generates ci-recovery.tsx*
Claude understands the component model and generates working orchestration scripts. This is the “agents write agents” loop:
  1. Describe the workflow you want to Claude Code
  2. Claude generates a Smithers plan (TSX)
  3. You review it like any other code
  4. Smithers executes it as a durable workflow
  5. Ralph until it’s done

​
Inspecting State

View execution history and state with the database: 
# View execution history
smithers db executions

# View current state
smithers db state

# View database statistics
smithers db stats

​
Next Steps

Durable Ralphing

Understand the execution model

Claude Component

Learn the full Claude API

Database Persistence

Flight recorder for your workflows

Examples

Copy-paste starter workflows