Tour

A code-review workflow, built one capability at a time; each step is a diff against the last. Reading time: 15 minutes.

1. Install and scaffold

bunx smithers-orchestrator init
bun add smithers-orchestrator zod@^4
bun add -d typescript @types/bun
codex login

init creates .smithers/ with seeded workflows, prompts, and components. The bun deps add Smithers and Zod (schemas); codex login authorizes your Codex subscription for workflow workers.

Zod v4 is required. Smithers introspects output schemas via Zod v4 internals; pin zod@^4, or a v3 schema fails building an agent command with the cryptic error undefined is not an object (evaluating 'schema._zod.def').

A minimal tsconfig.json:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true
  }
}

jsxImportSource is the only Smithers-specific line; it routes JSX through the workflow runtime instead of React DOM.

2. One-task workflow

/** @jsxImportSource smithers-orchestrator */
import { createSmithers, Sequence, Task } from "smithers-orchestrator";
import { z } from "zod";

const { Workflow, smithers, outputs } = createSmithers({
  input: z.object({ name: z.string() }), // types ctx.input
  greeting: z.object({ message: z.string() }),
});

export default smithers((ctx) => (
  <Workflow name="hello">
    <Sequence>
      <Task id="greet" output={outputs.greeting}>
        {{ message: `Hello, ${ctx.input.name}` }}
      </Task>
    </Sequence>
  </Workflow>
));

createSmithers registers Zod schemas as durable output relations the runtime manages. outputs.greeting is the typed reference for the greeting schema; using it as the output prop catches typos at compile time (outputs.greting is a type error). The input key is special: its schema types ctx.input, so ctx.input.name is a checked string, not unknown; every other key, like greeting here, is an output table. Omitting input leaves ctx.input untyped, forcing a defensive guard on each field (ctx.input?.name ?? "world"). Fresh runs and graph previews parse input through this schema, so Zod defaults and transforms are available in ctx.input. Continue to coalesce fields declared optional or nullable. This Task has no agent, just a literal value. Run it.

bunx smithers-orchestrator up workflow.tsx --input '{"name":"world"}'

Inspect:

bunx smithers-orchestrator ps                  # find the run id
bunx smithers-orchestrator inspect RUN_ID    # structured state
bunx smithers-orchestrator output RUN_ID greet --pretty  # typed node output

A controller or custom monitor reads the same output through Gateway getNodeOutput({ runId, nodeId: "greet" }), never the backing store directly; SQLite/PGlite/Postgres are interchangeable runtime details.

3. Add an agent task

Replace the literal Task with an agent Task whose output is structured.

/** @jsxImportSource smithers-orchestrator */
import { CodexAgent, createSmithers, Sequence, Task } from "smithers-orchestrator";
import { z } from "zod";

const { Workflow, smithers, outputs } = createSmithers({
  input: z.object({ repo: z.string() }),
  analysis: z.object({
    summary: z.string(),
    issues: z.array(z.object({
      file: z.string(),
      line: z.number(),
      severity: z.enum(["low", "medium", "high"]),
      description: z.string(),
    })),
  }),
});

const analyst = new CodexAgent({
  model: "gpt-5.6-sol",
  instructions: "You are a senior code reviewer. Return structured JSON.",
});

export default smithers((ctx) => (
  <Workflow name="review">
    <Sequence>
      <Task id="analyze" output={outputs.analysis} agent={analyst}>
        {`Review the code in ${ctx.input.repo} and return analysis as JSON.`}
      </Task>
    </Sequence>
  </Workflow>
));

The runtime injects a JSON-schema description of outputs.analysis into the prompt, parses the agent’s response, validates against Zod, and persists. Validation failure triggers a retry.

4. A second task that depends on the first

Tasks see each other’s outputs through ctx.outputMaybe(...): an incomplete upstream returns undefined, and once it appears on a later render frame, the downstream Task mounts. When a Task consumes exactly one upstream output, <Task deps={{ analyze: outputs.analysis }}> with a (deps) => ... callback is more ergonomic; reach for ctx.outputMaybe to inspect content or gate multiple siblings.

/** @jsxImportSource smithers-orchestrator */
import { CodexAgent, createSmithers, Sequence, Task } from "smithers-orchestrator";
import { z } from "zod";

const AnalysisSchema = z.object({
  summary: z.string(),
  issues: z.array(z.object({
    file: z.string(),
    line: z.number(),
    severity: z.enum(["low", "medium", "high"]),
    description: z.string(),
  })),
});

const { Workflow, smithers, outputs } = createSmithers({
  input: z.object({ repo: z.string() }),
  analysis: AnalysisSchema,
  fix: z.object({
    patch: z.string(),
    filesChanged: z.array(z.string()),
  }),
});

const analyst = new CodexAgent({
  model: "gpt-5.6-sol",
  instructions: "You are a senior code reviewer. Return structured JSON.",
});

const fixer = new CodexAgent({
  model: "gpt-5.6-luna",
  config: { model_reasoning_effort: "medium" },
  instructions: "Write minimal, correct fixes as a unified diff.",
});

export default smithers((ctx) => {
  const analysis = ctx.outputMaybe(outputs.analysis, { nodeId: "analyze" });

  return (
    <Workflow name="review">
      <Sequence>
        <Task id="analyze" output={outputs.analysis} agent={analyst}>
          {`Review ${ctx.input.repo}`}
        </Task>
        {analysis ? (
          <Task id="fix" output={outputs.fix} agent={fixer}>
            {`Fix these issues:\n${analysis.issues.map(i =>
              `- [${i.severity}] ${i.file}:${i.line} - ${i.description}`
            ).join("\n")}`}
          </Task>
        ) : null}
      </Sequence>
    </Workflow>
  );
});

Render 1 mounts only analyze. Render 2, once analyze finishes: analysis is populated, fix mounts and runs. That’s the whole reactivity story: no hooks, no subscriptions, just JSX conditionals over persisted state. The same shape covers branching, parallel groups, and loops: ?: is the inline conditional form, <Branch> the declarative form for explicit then/else (as props, not children):

<Parallel maxConcurrency={3}>
  <Task id="lint"  output={outputs.lint}  agent={linter}>...</Task>
  <Task id="test"  output={outputs.test}  agent={tester}>...</Task>
  <Task id="audit" output={outputs.audit} agent={auditor}>...</Task>
</Parallel>

<Branch
  if={!!analysis && analysis.issues.length > 0}
  then={<Task id="fix"  output={outputs.fix}  agent={fixer}>...</Task>}
  else={<Task id="ship" output={outputs.ship} agent={shipper}>...</Task>}
/>

<Loop until={!!review?.approved} maxIterations={5}>
  <Task id="implement" output={outputs.impl} agent={implementer}>...</Task>
  <Task id="review"    output={outputs.review} agent={reviewer}>...</Task>
</Loop>

5. An approval gate

Pause for a human: the runtime persists the decision and exits cleanly. The operating agent relays the question, then approves or denies through the CLI; resume continues from the gate.

import { Approval } from "smithers-orchestrator";

{analysis ? (
  <Approval
    id="confirm-fix"
    output={outputs.confirmFix}
    request={{
      title: `Apply fixes for ${analysis.issues.length} issues?`,
      summary: analysis.summary,
    }}
    onDeny="skip"
  >
    {/* children rendered after approval */}
  </Approval>
) : null}

{ctx.outputMaybe(outputs.confirmFix, { nodeId: "confirm-fix" })?.approved ? (
  <Task id="fix" output={outputs.fix} agent={fixer}>
    {`Apply patches`}
  </Task>
) : null}

Operator side (you, the agent, run these for the human; never hand them off):

bunx smithers-orchestrator ps --status waiting-approval     # find paused runs
bunx smithers-orchestrator inspect RUN_ID                  # see the request
bunx smithers-orchestrator approve RUN_ID --node confirm-fix --by alice
bunx smithers-orchestrator up workflow.tsx --run-id RUN_ID --resume true

onDeny controls rejection: "fail" aborts the run, "continue" proceeds without the approved branch, "skip" skips the gated tasks.

6. Crash, then resume

Every completed task’s output sits in SQLite. A crash, kill, or restart loses no work; the next run with --resume true skips finished tasks.

bunx smithers-orchestrator up workflow.tsx --input '{"repo":"."}' --run-id review-1
# ...analyze finishes, fix is mid-flight, you Ctrl+C

bunx smithers-orchestrator up workflow.tsx --run-id review-1 --resume true
# analyze is skipped (already in DB), fix re-runs from scratch (was incomplete)

A Smithers run is killed partway through, then resumes: the completed task is skipped, the in-flight task re-runs as a new attempt, and the run finishes — The same crash-and-resume mechanic: a run is killed mid-task, then resuming skips the finished work and re-runs only the interrupted task from its last persisted frame.

In-flight attempts are marked stale and retried on resume. Same input + same code = same task IDs, so resume is deterministic. For unattended recovery, run the supervisor:

bunx smithers-orchestrator supervise --interval 30s --stale-threshold 1m

It auto-resumes runs whose owner process died.

What you skipped (and where to find it)

Time travel (replay a frame, fork a run, diff two runs): bunx smithers-orchestrator replay|fork|diff|timeline, detailed in How It Works → Time travel.
Scorers (attach evaluators to Tasks): Recipes → Scoring tasks.
Memory (cross-run facts and message history): How It Works → Memory.
RAG, voice, OpenAPI tools: opt-in fragments, indexed in llms.txt.
Tool sandbox (read/grep/bash with path containment): Recipes → Tools.

Start

Articles

Learn

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

1. Install and scaffold

2. One-task workflow

3. Add an agent task

4. A second task that depends on the first

5. An approval gate

6. Crash, then resume

What you skipped (and where to find it)

Read next

​1. Install and scaffold

​2. One-task workflow

​3. Add an agent task

​4. A second task that depends on the first

​5. An approval gate

​6. Crash, then resume

​What you skipped (and where to find it)

​Read next

1. Install and scaffold

2. One-task workflow

3. Add an agent task

4. A second task that depends on the first

5. An approval gate

6. Crash, then resume

What you skipped (and where to find it)

Read next