> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Why React?

> Smithers is a JSX runtime because agents are extraordinarily good at writing React.

The first thing people ask is some version of: *React is for UI. Why is your workflow engine pretending to be a frontend?*

Short answer: **agents are incredible at writing React.** That's the whole pitch. Every other property of Smithers, including durability, time travel, hot reload, and composability, falls out for free from that one premise.

## The shape of the runtime

Forget orchestration. Here is everything Smithers does:

* **State lives in a durable store.** Every task output, every frame, every approval, and every signal persists through Smithers' storage adapter (SQLite, PGlite, or Postgres).
* **Workflows return a React tree.** The tree describes which tasks should run and in what order. Host elements are `smithers:task`, `smithers:sequence`, `smithers:parallel`, `smithers:branch`, and `smithers:ralph` (not UI primitives), exposed to workflow authors as the React components `<Task>`, `<Sequence>`, `<Parallel>`, `<Branch>`, and `<Loop>` (`<Loop>` is an alias for `<Ralph>`).
* **As tasks finish, React rerenders.** The next render reads the updated durable state and the tree comes back different: branches missing before now mount, loops grow another iteration, conditionals flip.
* **Every frame is stored durably.** Each render produces a snapshot of the workflow plan, indexed by frame number, with the outputs that triggered it.

That's it. Render → execute → persist → render. The render is pure. The persistence is durable. The loop is the program.

<Frame caption="Four stages, one cycle. The render is a pure function of state; persistence makes it durable; the re-render is what makes the plan evolve as tasks finish.">
  <img src="https://mintcdn.com/smithers/xegNOoNr9NbWn5pb/images/why/render-loop.svg?fit=max&auto=format&n=xegNOoNr9NbWn5pb&q=85&s=c43f8c9d65d84c67006fac414e01f44a" alt="The Smithers runtime loop: render the workflow tree, extract ready tasks, execute them, persist outputs, then re-render against the new state" width="820" height="280" data-path="images/why/render-loop.svg" />
</Frame>

## What you get for free

Once the runtime has that shape, a stack of useful properties just *appear*:

**Agents inspect state easily through one control plane.** Ask what happened on
frame 17 of run `abc123` and the agent uses Gateway `getDevToolsSnapshot`,
`getNodeOutput`, or the public `tree`/`inspect` CLI, never needing to know the
workspace's storage backend or query runtime tables directly.

**Time travel is real: every frame is a snapshot** of its nodes, outputs, and active jj pointer, recorded in the durable store. Rewinding to frame 5 calls revertToJjPointer to restore the working tree to that jj state and replay the workflow against the exact source that ran originally: real state, not a log of it.

<Frame caption="Because every frame is durable, the Gateway can fork a run from an earlier snapshot while the original timeline stays intact.">
  <img src="https://mintcdn.com/smithers/xegNOoNr9NbWn5pb/images/why/task-fork.gif?s=95cc84444dfb5b3e11d9882d7540e1b7" alt="A Smithers run rewinds to an earlier frame and forks into a second branch that retries the work a different way" width="1200" height="675" data-path="images/why/task-fork.gif" />
</Frame>

**The whole React hook ecosystem becomes available for orchestration.** `useMemo`, `useContext`, custom hooks: they all work. Want to factor the "wait for approval, then branch" pattern into a `useApprovalGate()` hook? Go ahead. The reconciler doesn't know the difference between a Task and a `<div>`.

**Complex workflows are easier for humans to read.** React's functional composability means a 30-task pipeline reads like a component tree, not a YAML graph. A reviewer can `cmd+click` a `<TicketPipeline>` to see what it expands to. Reuse is just import-and-render.

**LLM prompts can be MDX files that take props.** A prompt is a component. It accepts inputs, embeds expressions, and renders to a string the agent sees. Versioning prompts means versioning files. Testing prompts means rendering them.

These are real benefits. But they're all *secondary*.

## The actual reason: agent experience

Every workflow engine asks the agent to learn a new DSL: a custom YAML schema, a node-and-edges graph format, a state-machine transition table, each a domain the agent has seen little training data for.

React, by contrast, is one of the most heavily represented domains in the training corpus of every modern model: JSX, hooks, conditional rendering, composition patterns, prop drilling, state colocation. Agents have seen millions of examples of each and write it fluently, idiomatically, without coaching.

So Smithers does the obvious thing: **map orchestration onto a domain agents are already optimized for.** A workflow becomes a component tree, a dependency a conditional render, a loop `<Loop>` with the same `key` semantics agents already know, and an iteration's previous output reads with the same mental model as state in a parent component.

This is agent experience: just as DX (developer experience) is the discipline of designing tools humans love, agent experience designs tools agents are good at. Setting an agent up to perform well on a hard problem often just means expressing the problem in a domain it has already mastered.

That is why, as Smithers has stabilized, it has become the orchestration tool agents reach for. Other engines are more featureful and the API isn't small, but **agents write workflows that run correctly more often, with less back-and-forth coaching, than they do with bespoke DSLs.** They write a workflow, it runs. They debug a failed task, they fix it. They refactor a 200-task pipeline, they don't break it.

## The objection, answered

The skeptical objection persists: React is for views, and we've forced it to do another job.

This gets the history backwards: React is fundamentally a reconciler, a general-purpose engine that diffs a declarative tree against its prior version into a minimal set of imperative operations. React Native drives native views, Ink drives terminal UIs, React Three Fiber drives a 3D scene graph, and Smithers drives a task graph.

The reconciler is the abstraction. The DOM was just the first host. We're a different host.

## Read next

* [How It Works](/how-it-works): the render → execute → persist loop.
* [JSX API](/jsx/overview): setup, tsconfig, and the minimal workflow.
* [Tour](/tour): six-step worked example.
