Skip to main content
1

Run one command

From inside your project:
init asks one question, which coding agent do you prefer, shows what it detected (Claude Code, Codex, Pi, …), and scaffolds .smithers/ with the focused authoring pack (create-workflow, create-skill, docs-driven-development), installs dependencies, and installs that agent’s plugin (or skill). Former recipes live under examples/init-pack/; piped or non-interactive callers (CI, agents, --yes) skip the question and install defaults, and --no-tutorial skips the guided session.create-workflow is the scaffold’s star: describe the workflow you want and it writes that plus a companion skill document. Re-running init later only offers to update files that drifted.
2

Make sure your agent knows Smithers

Your agent drives Smithers. Two ways to give it the context it needs:
  • Have your agent read the docs. Ask it to run bunx smithers-orchestrator docs (concise index) or bunx smithers-orchestrator docs-full, or point it at https://smithers.sh/llms-full.txt. Quick, no install.
  • Install the plugin or skill for your harness so context is always loaded. Each page below has the exact install:
init already installs the best integration for your preferred agent: the Claude Code plugin, the Hermes/OpenClaw native plugins, or the curated skill for Codex, Pi, OpenCode, Kimi, Amp, and Antigravity. Use the page above for your harness to wire additional agents or add MCP.
3

Ask your agent to create a workflow

You don’t run Smithers, your coding agent does: you describe outcomes, it picks and runs the workflow. Ask it, in plain language:
“Use create-workflow to build a workflow that checks my API and keeps iterating until tests pass.”
Your agent runs create-workflow; a durable run completes and reports the generated workflow and companion skill path back to you.Run it yourself in a terminal and a cheap, fast model narrates the result: a short recap plus a self-contained HTML summary that opens in your browser (written under .smithers/reports/). Pass --no-report, or set SMITHERS_NO_REPORT=1, to skip it.
This runs the coding agent init detected (Claude Code, Codex, …), so have one installed and signed in.
4

Ask your agent to open the run UI

To watch a run live in your browser, ask your agent:
“Open the Smithers UI for that run.”
Your agent runs bunx smithers-orchestrator ui <RUN_ID>, which opens the run’s live status card (stages, output, any approval gates) in your browser. Keep it open while you hand off more work.
Your agent ran a workflow; pick what you need next.

Talk to your agent

How-to: phrase requests so your agent picks the right workflow every time.

Watch and steer

How-to: follow a live run, clear approvals, and redirect without touching code.

What you can do

Reference: the catalog of outcomes you can hand off, and what to say.

The few concepts you need

Explanation: the handful of ideas behind durable runs, gates, and loops.