Skip to main content
1

Run one command

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

Make sure your agent knows Smithers

Your agent drives Smithers, so it needs the Smithers context. Two ways to get it there:
  • 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 the context is always loaded. Each page below has the exact plugin/skill 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 for your harness above to wire additional agents or add MCP.
3

Ask your agent to create a workflow

You don’t run Smithers yourself - your coding agent does. 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 it reports the generated workflow and companion skill path back to you.When you run it yourself in a terminal, a cheap, fast model narrates the result: a short recap in the terminal 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. From here on, your agent drives Smithers for you - you describe outcomes, it picks and runs the workflow.
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, and any approval gates - in your browser. Keep it open while you hand off more work.
Your agent ran a workflow. From here, pick by 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 full 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.