smithers-orchestrator weekly downloads statistics

smithers-orchestrator

Run long-horizon coding-agent work as durable workflows.

Tell your coding agent to do real, multi-step work, then Smithers runs it for minutes or days with crash recovery, retries, human approvals, and full observability. The same workflow runs across Claude Code, Codex, Cursor, Pi, AI SDK models, and remote sandboxes.

This package is the published Smithers runtime: the engine, the smithers CLI, the JSX workflow primitives, the agent adapters, and the Gateway. Install it once and your coding agent drives the rest.

*Watch every step of a workflow run, pause execution, approve gates, and rewind to an earlier checkpoint. Independent steps can run at the same time.*

What you get

• 🛡️ Durable runs that survive crashes: every completed step is persisted the moment it finishes, so a run resumes from where it stopped instead of starting over. • 🔌 Any agent, any model: Claude Code, Codex, Cursor, Pi, Antigravity, and more, plus any model through the AI SDK. Swap the harness without rewriting the workflow. • 🛠️ Higher-quality output: review loops, human approvals, and evals give agents the structure that real work demands. • 🧩 A workflow builder, not a fixed library: init installs a focused authoring pack (create-workflow, create-skill, docs-driven-development); your agent designs, scaffolds, and documents new workflows — planning, implementation, review, debugging, tickets, audits, long-horizon missions — from a plain-English ask.

When to use Smithers

Smithers is the durable runtime for *coding-agent* work: when the unit of work is an agent editing a real repository over many steps, and you need that work to be inspectable, approvable, and recoverable. Use it when order matters across multiple AI steps, you need crash recovery, a human must approve or answer mid-run, or different tasks need different models. For a single prompt → single response, call your model provider's SDK directly; Smithers adds nothing there.

Get started

Smithers is driven by your coding agent, not a GUI you click. Your agent runs Smithers on your behalf: it scaffolds workflows, kicks off runs, watches them, and handles approvals.

One command sets everything up. From inside your project:

init does everything:

• Installs the smithers skill into the coding agents on your machine (Claude Code, Pi, and more), so your agent knows how and when to use Smithers. No mkdir, no curl. • Scaffolds .smithers/ with a focused authoring pack — create-workflow, create-skill, and docs-driven-development — so your agent builds the exact workflow you need instead of picking from a fixed library. Former starter workflows (hello, plan, review, debug, and more) are preserved as copyable patterns under examples/init-pack/.

Then just ask:

*"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 until the work is actually done.

Always run bunx smithers-orchestrator, never bunx smithers. On npm, smithers is an unrelated package. The installed binary alias smithers is only safe inside a project that resolves node_modules/.bin/smithers.

To wire the MCP server into every detected agent too, run bunx smithers-orchestrator mcp add. See Agent Support for the full per-agent matrix.

Drive it yourself

Prefer the CLI? Ask create-workflow to build something for you:

Or copy one of the 29 archived starter patterns (hello, plan, review, debug, and more) from examples/init-pack/ into .smithers/workflows/ and run it directly — see examples/init-pack/README.md for the full inventory.

Watch what's happening, whether your agent started the run or you did:

Run bunx smithers-orchestrator starters to browse plain-English starters, and bunx smithers-orchestrator workflow list to see what's installed.

Durable by default

Durability is the differentiator. Runs survive crashes, restarts, and flaky tools because every completed step is persisted to SQLite the moment it finishes. The runtime always knows what's done and what to run next. Approvals, human questions, retries, and replay are first-class.

That loop is the whole model: a task runs, its output is validated against a schema and written down, then the workflow re-renders from persisted state to decide the next task. A crash at any point resumes from the last write, not from the top.

Author your own

The curated init workflows are normal Smithers TSX files, and the archived starter catalog under examples/init-pack/ remains available to copy or adapt. Run create-workflow to author a repository-specific workflow from the same primitives. A workflow is a JSX tree of tasks, each with a Zod-validated output:

Each task output is validated against its Zod schema and persisted to SQLite. If the process crashes, Smithers resumes from the last completed node without re-running finished work.

| Component | Purpose |

| | Root container | | | AI or static task node | | | Ordered execution | | | Concurrent execution | | | Conditional execution | | | Repeat tasks until a condition is met |

There are many more: approvals, merge queues, sub-workflows, signals, timers, sagas, sandboxes, and composite patterns. See Components.

Package entry points

The main entry re-exports the full toolkit, so most code only needs import { ... } from "smithers-orchestrator". Dedicated subpaths exist for focused imports:

| Import | What it gives you |…

Description from the npm listing.