Skip to main content
Most teams should start with the workflow pack. It gives you a working .smithers/ directory with seeded workflows, prompts, and agent configuration instead of assembling the project structure by hand.
Installation is the one step a human may run by hand. Everything after it (starting runs, inspecting them, clearing approvals) is your coding agent’s job: install the agent skill, then ask the agent for outcomes instead of typing Smithers commands yourself.

​
Always Run with bunx

Agents, MCP configs, and docs should use bunx smithers-orchestrator <command>. Do not use bunx smithers: smithers is only the installed binary alias. On npm, smithers is an unrelated package, so bunx smithers can download and run something else entirely.
  • The published npm package is smithers-orchestrator.
  • bunx smithers-orchestrator ... works from any directory and uses the project-pinned dependency when one exists.
  • The package also installs a smithers binary alias. Use smithers ... only when the current environment intentionally provides that binary, such as a project script that resolves node_modules/.bin/smithers.
  • Avoid global installs: a global smithers on PATH can drift from the project version and shadow the project-pinned binary.
If you previously ran npm i -g smithers-orchestrator, uninstall it (npm rm -g smithers-orchestrator) and switch to bunx.

​
Updating Smithers

How you update depends on how you run Smithers:
  • bunx / npx (recommended): nothing to update. bunx smithers-orchestrator@latest <command> always resolves the newest published version, and inside a workflow project it uses the version pinned in package.json. To move a pinned project forward, bump the dependency. Running bunx smithers-orchestrator@latest init re-scaffolds with the latest, or you can edit the smithers-orchestrator version in .smithers/package.json directly.
  • Global install: upgrade with your package manager.
Or let Smithers do it for you. smithers update detects how the binary was installed and runs the right command (or, for a bunx/project install, prints exactly what to run):
Verify the installed version any time with:
Smithers also checks npm at most once a day and prints a one-line notice on an interactive run when a newer release is available. The same daily check compares your install’s SOTA model registry against the published one: when a release ships with new best-in-class models, the notice tells you to run smithers update and then bunx smithers-orchestrator init so installed workflows move to the latest agents. Disable the passive check with SMITHERS_NO_UPDATE_CHECK=1 (it is already skipped in CI, in JSON/agent output, and for non-interactive shells).

​
Clean reinstall

If you suspect a stale cache or a leftover global symlink shadowing the project version, remove the global install and the runner cache, then reinstall:
bunx/npx keep their own download caches; appending @latest forces them to fetch the newest version rather than reuse a cached one.
That scaffolds .smithers/ with files such as: The 29 former defaults are not installed. They remain complete, copyable graph and UI examples under examples/init-pack/ in the source repository. To overwrite an existing scaffold:

​
Install the Agent Skill

Smithers is driven by an AI agent (Claude Code, Codex, and friends) not a GUI you click. Your agent runs Smithers on your behalf: scaffolding workflows, starting runs, watching them, and clearing approvals. The smithers skill makes your agent fluent in that without making it read the whole docs site first, so you reach the aha moment faster. init auto-installs the curated Smithers skill into detected agents whose skill directory Smithers can write directly today: Claude Code and Pi (no mkdir, no curl). For other agents, use the MCP server plus standing instructions, or point the agent at docs-full below. To sync the generated Smithers CLI command skill set at any time:
That writes generated command-level skill files to supported skill locations, including the canonical ~/.agents/skills directory. It supports --no-global for project-scoped installs; unlike mcp add, it has no supported --agent target filter. The curated onboarding skill installed by init ships the full docs bundle (llms-full.txt) next to its SKILL.md, so supported agents can read the exact API on demand. Once Smithers is wired into your agent, just ask for the outcome, “orchestrate an agent to add rate limiting and keep iterating until the tests pass”, and the agent reaches for Smithers itself. For agents without a skills directory, point them at bunx smithers-orchestrator docs-full (prints the same bundle) or bunx smithers-orchestrator ask "<question>". To install skills where supported and register the MCP server into coding agents on your machine, see Agent Support. It covers Claude Code, Codex, Cursor, Copilot, Pi, Hermes, OpenClaw, and more.

​
When to Use Manual Installation

Use manual installation when embedding Smithers into an existing TypeScript codebase to author a standalone workflow project from scratch. See JSX Installation for the package list, TypeScript configuration, and optional MDX prompt setup.

​
Requirements

  • Bun >= 1.3
  • TypeScript >= 5
  • Model or provider credentials (e.g. Anthropic ANTHROPIC_API_KEY)
  • A version control system for snapshotting and isolating agent work: jj (Jujutsu) or git. jj is preferred and powers durability, time-travel, and per-task worktrees.

​
Version control

Smithers bundles jj. The optional @smithers-orchestrator/jj-<platform> package installs a vendored jj binary for your platform, so a fresh install works with no system jj. Resolution order is:
  1. SMITHERS_JJ_PATH: point this at a jj binary to override everything.
  2. The bundled binary for your platform.
  3. jj on your PATH.
If no bundled binary installed (an unsupported platform, or --no-optional) and neither jj nor git is on PATH, runs that need a worktree fail with a message telling you to install one. Check what Smithers found with bunx smithers-orchestrator workflow doctor (the vcs section reports the resolved jj and git). If the bundled jj exists but fails with EACCES, its executable bit was stripped during packaging or install. Fix the local install with chmod +x node_modules/@smithers-orchestrator/jj-*/bin/jj, reinstall, or set SMITHERS_JJ_PATH to a known-good jj binary.

​
After Installation

Quickstart

Run a seeded workflow immediately.

Set up in your harness

Wire Smithers into your agent and grab a copy-paste setup prompt.

Install the agent skill

Make your coding agent fluent in Smithers.

CLI Quickstart

The operational command cheatsheet.

JSX installation

Manual TSX authoring setup.

Project structure

How a standalone workflow project fits together.

Tools integration

The built-in tool sandbox.