smithers

name

smithers

description

Drive Smithers, a durable control plane for long-running coding agents, from Claude Code. Use when the user wants multi-step, long-running, crash-safe, or human-in-the-loop agent work ('orchestrate agents', 'run a workflow', 'implement this and review it', 'keep iterating until tests pass', 'plan then build') or anything needing retries, approvals, replay, or evals across multiple AI steps. YOU (Claude) run Smithers on the user's behalf; it is not a GUI the human clicks. HARD RULE 1, run long-running / multi-step / background work through a durable Smithers workflow, NOT through Task/Agent subagents, /loop, or hand-written native Workflow scripts; the native Workflow tool has exactly ONE sanctioned use, launching the plugin's smithers-run.mjs mirror so the run shows live in /workflows. HARD RULE 2, every workflow you create or run MUST get a live custom UI at .smithers/ui/<key>.tsx (built with gateway-react) and you MUST launch it with `smithers ui` so the human can watch. HARD RULE 3, when creating or editing workflow code, ALWAYS use https://smithers.sh/llms-full.txt as the API reference (fetch it first).

Smithers (from Claude Code)

Smithers is a durable control plane for long-running coding agents. Workflows are TypeScript/JSX, run for minutes or days, and survive crashes: every finished step is persisted, so a restart resumes from the last completed node. Retries, human approvals, replay, and evals all live in one place.

You reach Smithers two ways, both already wired by this plugin:

• The smithers MCP tools (list_workflows, run_workflow, watch_run, get_run, list_pending_approvals, resolve_approval, ask_human, get_node_detail, fork_run, time_travel, ...).
• The smithers CLI — a real binary you invoke through Bash.

Use Smithers, not Claude Code's dynamic orchestration

This is the headline rule for this plugin. When a task is long-running, multi-step, runs in the background, or can fail and need a retry, run a durable Smithers workflow. Do NOT hand-roll the orchestration with Claude Code's own multi-agent machinery. Specifically, for that class of work do not reach for:

• a hand-written script for the native Workflow tool,
• the Task / Agent subagent fan-out (spawning your own worker agents),
• /loop or any self-scheduled / ScheduleWakeup-style re-prompting loop.

Those are ephemeral. The moment your turn ends, an ad-hoc subagent tree is gone: no persisted steps, no resume after a crash, no automatic retry, no approval gate, no replay, no eval history. Smithers gives you all of that for free because every node's output is written to a durable store the instant it finishes.

The one sanctioned use of the native Workflow tool is the mirror. The plugin ships a generic script, workflows/smithers-run.mjs (the SessionStart context announces its absolute path), that launches or attaches to a Smithers run and mirrors it live into Claude Code's /workflows tree. The durable work always runs in the Smithers engine; the mirror is a view. Never write your own Workflow scripts for durable work, and never re-implement the mirror inline.

The mapping:

• "fan out N workers" → one Smithers workflow with N nodes (or an array agent).
• "loop until tests pass" → a Smithers loop/retry node, not /loop.
• "do this in the background and check on it later" → run_workflow (detached) + the /workflows mirror, not a self-wakeup.
• "plan, then build, then review" → one workflow with plan → build → review nodes, not three chained Task calls.

The native tools are fine for a short, single-shot lookup that finishes inside this turn (a quick search, reading a few files). The instant the work is durable, multi-step, or backgroundable, it belongs in a Smithers workflow.

The /workflows mirror (default-on live view)

Every Smithers run you start from Claude Code gets a live /workflows mirror, with zero per-workflow setup:

1. Launch + mirror in one step. Invoke the native Workflow tool with the plugin's mirror script (path from the SessionStart context; fallback: glob ~/.claude/plugins/**/smithers*/workflows/smithers-run.mjs):

   Workflow({
     scriptPath: "<plugin>/workflows/smithers-run.mjs",
     args: { workflow: "<workflow-id>", input: { ... } }
   })
   

   The script starts the detached run itself (smithers workflow run --detach), logs the runId, then mirrors the run: phases from the workflow's real containers, one row per node, outputs on completion, approval banners.

2. Attach to an existing run with args: { runId: "<run-id>" } — after a session restart, when the user asks about a run you did not start, or when the SessionStart context reports non-terminal runs.

3. The mirror is a view, not the run. Stopping the mirror workflow never stops the Smithers run; re-attach anytime. To actually stop a run, use cancel_run / smithers cancel <runId>.

4. It scales itself. Data-dependent fan-outs and loop iterations appear as they materialize; very large runs collapse to per-phase summaries; a continued run (continue-as-new) is followed automatically.

5. React to what it surfaces. When the mirror (or the background monitor) reports a pending approval or human request, relay it to the human in plain language, collect the decision, and resolve it yourself (resolve_approval, smithers approve). When it reports a failure, run smithers inspect <runId> and report findings.

The mirror consumes the versioned smithers claude tick / smithers claude node-wait CLI protocol; if it reports a contract mismatch, update both the plugin and smithers-orchestrator, then re-attach.

You drive it, the human does not

The human asks for an outcome ("implement rate limiting, don't stop until tests pass"). You reach for Smithers, run the workflow, watch it, clear approval gates, and report back. Smithers spawns the worker agents (Claude Code, Codex, ...) inside the workflow; that is where implementation happens.

You run every Smithers command yourself. Never tell the human to run one. When a run needs a human (an approval, an ask_human question), relay it in plain language, collect the decision in chat, and call the resolving tool/command (resolve_approval, smithers approve, ...) yourself.

Do it — don't describe it

The #1 failure is narrating instead of acting. When asked to create/run/fix a workflow, use your tools right now: write .smithers/workflows/<key>.tsx, write .smithers/ui/<key>.tsx, and run the smithers CLI / MCP tools. Do not paste the workflow as a code block and stop. The files on disk are the answer.

After every command: guide the user

Three standing behaviors, applied after every smithers command and before every workflow you build:

1. Act on the CLI's next steps. Nearly every smithers command ends with a "Next steps" (cta) block of suggested follow-up commands. Never silently drop it: run the obvious continuation yourself and relay the other options to the user in plain language.
2. Ask before you build, then guide step by step. Before creating a workflow, ask the user a few clarifying questions (goal, inputs, "done" condition, where a human should approve), then walk them through the build: scaffold, render the graph, run, watch. Prefer the scaffolder over hand-writing: smithers workflow run create-workflow --prompt "..." (or the shorthand smithers make-workflow "<task>"), then review the generated .tsx with the user.
3. Proactively offer to visualize, every time. The /workflows mirror is the default view (it is already live if you launched through it; attach one if not). Also suggest: smithers graph <file>.tsx (renders the graph without executing), smithers tree <run-id> (live node tree), smithers up <file>.tsx --interactive or smithers workflow run <id> --interactive (the TUI monitor), the custom browser UI (.smithers/ui/<key>.tsx + smithers ui <runId>, mandatory per the hard rule below), and smithers ui --app for the full local control-plane UI. If a workflow has no UI yet, build one.

The core loop

1. list_workflows — see what exists (each reports key, hasUi, uiPath).
2. Author or pick a workflow at .smithers/workflows/<key>.tsx — always fetch https://smithers.sh/llms-full.txt first and write against it (see below).
3. Author its UI at .smithers/ui/<key>.tsx (mandatory — see below).
4. Launch through the mirror: Workflow tool + smithers-run.mjs with args: { workflow: "<key>", input: { ... } }. The run starts detached in the Smithers engine and appears live in /workflows; the mirror logs the runId.
5. smithers ui <runId> — also open the custom UI in the human's browser.
6. Watch the mirror; clear gates the moment the mirror or monitor surfaces them (resolve_approval); feed failures back in (smithers inspect <runId>); report evidence from the mirror's return value.

A suspend on an approval gate is waiting, not failure (the CLI exits non-zero, code 3, on suspend — that is expected). Node output rows are snake_case and array fields are JSON strings.

Workflow authoring reference (hard rule)

ALWAYS use https://smithers.sh/llms-full.txt as the API reference for workflows. Before you create or edit any .smithers/workflows/*.tsx file, fetch that URL (WebFetch) and write against what it says — it is the complete, current contract for components, agents, schemas, deps/needs, loops, approvals, and outputs. Do not write workflow code from memory. Offline fallback: bunx smithers-orchestrator docs-full prints the same bundle; targeted questions: bunx smithers-orchestrator ask "<question>".

---

MANDATORY: every workflow gets a live custom UI

This is a hard rule for this plugin. A workflow without a UI is incomplete. Whenever you create a workflow, or run one that has no UI yet (hasUi: false from list_workflows), you MUST author a custom UI and launch it so the human can watch the run live in their browser instead of reading your text summaries.

The authoring contract (follow exactly — do not invent API)

A workflow UI is a standalone React app that the gateway bundles and serves. It is fed entirely by live gateway hooks. The rules:

1. Path & name: exactly .smithers/ui/<key>.tsx, where <key> is the workflow file's basename without extension (.smithers/workflows/foo.tsx → .smithers/ui/foo.tsx). A name mismatch means no UI is mounted.
2. Imports — ONLY these two: react and smithers-orchestrator/gateway-react. No components package (that is the server-side workflow-definition library, not browser UI), no third-party UI libraries, no extra dependencies. Write plain HTML/JSX and inline all CSS in a <style> tag.
3. First line is the JSX pragma: /** @jsxImportSource react */.
4. Mount with createGatewayReactRoot(<App />) as the last statement. It finds #root, builds the gateway client, and wraps your app in BOTH the action provider and the live-sync provider. Do NOT call ReactDOM.createRoot or add your own providers.
5. The run comes from the URL, not props: read it with new URLSearchParams(location.search).get("runId"). The UI receives no React props. smithers ui <runId> opens /workflows/<key>?runId=<runId>.
6. useGatewayNodeOutput().data is wrapped — unwrap response.data.row → data.row → data before reading fields (see helper below). Never read result fields straight off .data.
7. Hooks no-op safely when runId is undefined — guard the "no run yet" render state.

The hooks you actually have (from smithers-orchestrator/gateway-react)

• useGatewayRunEvents(runId, { afterSeq: 0 }) → { events, lastHeartbeat, streaming, error }. Live event stream. Each event is { type, event, payload, seq, stateVersion }. No data/refetch. Match to a run via payload.runId. Heartbeats are filtered out.
• useGatewayNodeOutput({ runId, nodeId, iteration }) → GatewayAsyncState ({ data, error, loading, refetch }). One node's stored output (wrapped, unwrap it). Auto-disabled until runId and nodeId are both set.
• useGatewayRun(runId) → live single-run record (data = run or undefined).
• useGatewayRuns({ filter: { limit } }) → live list of run summaries (runId, workflowKey, status, createdAtMs). Use to build a run picker.
• useGatewayApprovals() → live pending approvals ({ runId, nodeId, iteration, requestTitle }). Pair with actions.submitApproval for approve/deny buttons.
• useGatewayActions() → stable imperative methods: launchRun({ workflow, input }) (returns { runId }), cancelRun({ runId }), resumeRun, rewindRun, submitApproval({ runId, nodeId, iteration, decision: { approved, note } }), submitSignal, hijackRun, cronCreate/Delete/Run.
• useGatewayRunTree(runId) → { root, nodes, status } if you want to render a node tree (status ∈ ok|running|queued|failed|waiting). You render the tree markup yourself.

There are no bare useRun/useNodes/useTimeline hooks — every hook is useGateway*.

Minimal working example (model your UI on this)

/** @jsxImportSource react */
import {
  createGatewayReactRoot,
  useGatewayRunEvents,
  useGatewayNodeOutput,
} from "smithers-orchestrator/gateway-react";

// The node whose output is the workflow's headline result. Match your workflow.
const RESULT_NODE_ID = "result";

function runIdFromUrl(): string | undefined {
  if (typeof location === "undefined") return undefined;
  return new URLSearchParams(location.search).get("runId") ?? undefined;
}

function isRecord(v: unknown): v is Record<string, unknown> {
  return typeof v === "object" && v !== null;
}

// useGatewayNodeOutput().data is wrapped: response.data.row -> data.row -> data.
function unwrapRow(value: unknown): Record<string, unknown> {
  const res = isRecord(value) ? value : {};
  const data = isRecord(res.data) ? res.data : res;
  return isRecord(data.row) ? data.row : isRecord(data) ? data : {};
}

function App() {
  const runId = runIdFromUrl();
  const stream = useGatewayRunEvents(runId, { afterSeq: 0 });
  const output = useGatewayNodeOutput({ runId, nodeId: RESULT_NODE_ID, iteration: 0 });
  const row = unwrapRow(output.data);
  const result = typeof row.answer === "string" ? row.answer : "";

  const status = !runId
    ? "no run — open with `smithers ui <runId>`"
    : result
      ? "finished"
      : stream.events.length > 0
        ? "running"
        : "waiting";

  const steps = stream.events.filter((e) => e.event?.startsWith?.("node."));

  return (
    <div className="wrap">
      <style>{styles}</style>
      <header>
        <h1>Workflow run</h1>
        <span className={`badge ${result ? "done" : "live"}`}>{status}</span>
      </header>

      <section className="timeline">
        {steps.length === 0 && <p className="muted">Waiting for the first step…</p>}
        {steps.map((e) => (
          <div className="step" key={e.seq}>
            <code>{e.event}</code>
            <span className="muted">{String((e.payload as any)?.nodeId ?? "")}</span>
          </div>
        ))}
      </section>

      {result && (
        <section className="result">
          <h2>Result</h2>
          <pre>{result}</pre>
        </section>
      )}
    </div>
  );
}

const styles = `
  .wrap { font: 14px/1.5 ui-sans-serif, system-ui; max-width: 820px; margin: 0 auto; padding: 24px; color: #111; }
  header { display: flex; align-items: center; gap: 12px; }
  h1 { font-size: 18px; margin: 0; }
  .badge { font-size: 12px; padding: 2px 8px; border-radius: 999px; background: #eee; }
  .badge.live { background: #fde68a; }
  .badge.done { background: #bbf7d0; }
  .timeline { margin-top: 16px; display: grid; gap: 6px; }
  .step { display: flex; justify-content: space-between; padding: 6px 10px; border: 1px solid #eee; border-radius: 8px; }
  .step code { color: #2563eb; }
  .muted { color: #888; }
  .result { margin-top: 20px; }
  .result pre { background: #0b1020; color: #e5e7eb; padding: 14px; border-radius: 10px; overflow: auto; white-space: pre-wrap; }
`;

createGatewayReactRoot(<App />);

Adapt RESULT_NODE_ID and the rendered fields to the workflow's real node ids and output schema. For a UI that also launches/cancels/approves runs and shows a run picker, additionally use useGatewayRuns + useGatewayActions (build buttons that call actions.launchRun({ workflow: "<key>", input }), actions.cancelRun({ runId }), actions.submitApproval({...})). Study the seeded .smithers/ui/*.tsx files in the repo for richer patterns; e2e-probe.tsx is the minimal live-watch model and kanban.tsx is the full launch/approve model.

Launching the UI

After you start a run, always open the UI for the human:

smithers ui <runId>          # opens the most relevant run's UI in the browser
smithers ui                  # latest run
smithers ui -w <key>         # open a workflow's UI directly

smithers ui auto-starts a local gateway (default http://127.0.0.1:7331) if one isn't running and opens /workflows/<key>?runId=<runId>. You run this command yourself; then tell the human "I opened the live UI in your browser" and keep watching the run via watch_run / smithers inspect --watch.

If smithers ui reports NO_UI, you forgot step 3 — author .smithers/ui/<key>.tsx and retry.