Smithers turns agent runs into durable, rewindable timelines

The problem: ephemeral agent fan-out

Coding agents like Claude Code and Codex can already spawn subagents and coordinate them within a single session. The README is blunt about the limitation: that fan-out dies when the session ends or crashes, it is tied to one vendor, and an approval blocks the terminal. Smithers exists to make that orchestration durable. Every completed step is persisted the moment it finishes, so a run resumes from where it stopped instead of starting over. The intended user is a developer or team that needs an agent to change a repository across many steps, with the ability to pause for human approval, run review loops, and recover from failures. The README's own decision table says it plainly: if you want one answer from one prompt, call the model directly; Smithers is for when the work is a real, multi-step editing session.

How a run is a database, not a log

The core mechanism is that every step is a database row. That single design choice gives you live watching, rewind, fork, and replay without building a separate audit trail. The README describes time travel as forking a run from any earlier frame to branch an alternate timeline. Because each step is persisted, a crash mid-loop resumes at the current iteration, not at iteration one. The workflow itself is a JSX tree of tasks, defined with primitives like <Loop>, and wrapped in a createSmithers call that declares typed inputs and outputs. The example in the README shows a coder agent and a reviewer agent, both CodexAgent instances, with the reviewer running in a read-only sandbox. The Loop primitive repeats tasks until a condition is met, which is exactly the structure that a one-shot agent call cannot give you: implement, review, feed feedback back, repeat until approved.

Getting started: one command and a prompt

Smithers is driven by your coding agent, not by a GUI. The README stresses that you never write a workflow by hand; you describe the outcome in plain English and your agent authors the workflow from the same primitives the built-in pack uses. The setup is a single command run from inside your project: bunx smthrs init. That command installs the smithers skill into the coding agents on your machine, so your agent knows how and when to use Smithers, and it scaffolds a .smithers/ directory with the authoring workflows create-workflow, create-skill, and docs-driven-development. After init, you ask something like "orchestrate an agent to add rate limiting and keep iterating until the tests pass." Your agent picks the right workflow, starts the run, and keeps going through retries and review loops. To also wire the MCP server into every detected agent, you run bunx smthrs mcp add. The README points to smithers.sh/agents/overview for the full per-agent support matrix.

The workflow file as a versioned artifact

One of the sharpest differences from letting an agent orchestrate itself is that a Smithers workflow is a file you can version, review, and rerun. The README contrasts this with orchestration that is "a prompt you retype." With Smithers, the workflow is a JSX file that declares agents, models, and review loops. The example shows a CodexAgent with a specific model and a reasoning effort config, plus a reviewer with a different model and a read-only sandbox. That file is something a team can put under version control and inspect in a code review. The trade-off is that you now have a codebase for your agent orchestration. You need to maintain it, review changes to it, and understand what the primitives do. The README claims zero config because you don't hand-write workflows, but that only holds if you trust your agent to generate correct JSX. For a team that wants reproducibility, this is a strength; for a solo developer who wants a quick script, it is overhead.

Memory across runs and the Hindsight catch

Smithers includes a memory feature that works locally out of the box. You wrap tasks in a <Memory> component, and agents recall what earlier runs learned, pick up remember and recall tools mid-task, and retain a digest afterward. That is useful for long-running projects where a later run should not repeat mistakes from an earlier one. The README notes that semantic recall by meaning requires connecting Hindsight, a separate service at smithers.sh/guide/setup/semantic-memory. That is a real limitation: the default memory is likely keyword-based or exact-match, and the more powerful semantic version is an external dependency. If your workflows depend on recalling information by meaning, you need to set up and maintain Hindsight, which adds operational cost. The README does not specify what Hindsight costs or whether it is self-hosted, so you should check that guide before committing.

Alternatives: Temporal and LangGraph take different bets

The README links to comparison pages against Temporal and LangGraph. Temporal is a general-purpose durable workflow engine that has been around for years; it is not agent-specific. Temporal gives you durable execution and retries, but you write workflows in code that runs on a Temporal server, and it has no built-in notion of a coding agent or a sandbox. LangGraph is a graph-based orchestration framework for LLM applications; it is more flexible about control flow but does not persist every step as a database row by default, and it is not tied to coding-agent harnesses. Smithers sits in between: it is specifically for coding agents, it persists steps as rows, and it lets you swap harnesses without rewriting the workflow. The real difference is that Smithers is opinionated about the unit of work: an agent editing a repository. If your orchestration involves non-agent tasks like database migrations or human steps outside a terminal, Temporal is likely a better fit. If you need fine-grained graph control over LLM calls, LangGraph may be more appropriate.

Limitations and wrong-tool cases

The README is honest about when Smithers is the wrong tool. If you want a single answer from a single prompt, it says to call the model directly. Smithers is also not a GUI; it is driven by your coding agent, so if you expect a dashboard you click, this is not it. The observability is real, but it is built on the agent's own actions, so the quality of the timeline depends on how well the agent structures its steps. The README does not mention any support for non-coding tasks, so using it for general workflow automation is out of scope. Another limitation is that the workflow is JSX, which is a specific syntax; if your team is not comfortable with JSX or with the createSmithers pattern, there is a learning curve. The README also notes that the built-in pack includes a focused set of workflows, and former starters are only examples, so you may need to author your own workflows for anything beyond the provided patterns. The README does not specify how approvals are handled in a headless CI environment, which is a gap you should investigate.

Maintenance, license, and release cadence

Smithers is MIT licensed, which means you can use it in commercial projects without per-seat fees, but you get no warranty. The repository is under active development: the latest release at the time of writing is v0.35.0, with v0.34.0 and v0.33.0 within the previous two weeks. That cadence suggests the API may still be shifting, so pin your version and watch the release notes. The README mentions a comparison page and an awesome-smithers list, so there is some ecosystem material, but the core is a single package. The project is written in JavaScript, so it runs on Node and Bun; the init command uses bunx, which implies Bun is a dependency for setup. If your team does not use Bun, you may need to install it. The documentation is hosted on smithers.sh, and the README links to a tour for a deeper walkthrough. The maintenance cost is that you are adopting a young project, so expect breaking changes between minor versions until it stabilizes.

Editorial conclusion

Adopt Smithers if your unit of work is a multi-step agent editing a real repository that must survive crashes, require human approvals, or need to be replayed and forked. Skip it if you only need a single answer from a single prompt; call the model directly. Before adopting, verify that the harness you use is in the per-agent support matrix on smithers.sh, and check whether the built-in skill installs cleanly into your agent. Also confirm that your team accepts a workflow file as a versioned artifact, since that is the core shift from ad-hoc orchestration. The project is under active development with frequent releases, so pin the version you deploy.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes