Skip to main content
Most teams should start with the workflow pack: a working .smithers/ directory with seeded workflows, prompts, and agent configuration, rather than hand-assembling the project structure.
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 smthrs <command>. Do not use bunx smithers: it’s only the installed binary alias; on npm smithers is an unrelated package, so bunx smithers can download and run something else.
  • The published npm package is smthrs.
  • bunx smthrs ... works from any directory, using the project-pinned dependency when one exists.
  • Use the smithers alias only when the environment intentionally provides that binary, e.g. a project script resolving node_modules/.bin/smithers.
  • Avoid global installs: a global smithers on PATH can drift from and shadow the project-pinned version.
If you previously ran npm i -g smthrs, uninstall it (npm rm -g smthrs) and switch to bunx.

​
Updating Smithers

How you update depends on how you run Smithers:
  • bunx / npx (recommended): nothing to update. bunx smthrs@latest <command> resolves the newest published version; inside a workflow project it uses the version pinned in package.json. To move a pinned project forward, bump the dependency, run bunx smthrs@latest init to re-scaffold, or edit the smthrs version in .smithers/package.json directly.
  • Global install: upgrade with your package manager.
Or let smithers update do it: it detects the install method and runs the right command (or, for a bunx/project install, prints what to run):
Once the upgrade finishes, the update re-syncs every Smithers-owned skill (the generated CLI command skills and the curated smithers skill) so an upgrade never leaves an agent reading the previous release’s SKILL.md and llms-full.txt. This runs in agent and CI sessions too, not just interactive terminals. Opt out with SMITHERS_NO_SKILL_REFRESH=1, and run bunx smthrs skills add yourself if the sync is skipped or fails. Verify the installed version:
Smithers also checks npm at most once a day and prints a one-line notice on an interactive run when a newer release exists, or when its SOTA model registry falls behind the published one: run smithers update then bunx smthrs init to move workflows onto the latest agents. Disable it with SMITHERS_NO_UPDATE_CHECK=1 (already off in CI, JSON/agent output, and non-interactive shells).

​
Clean reinstall

If you suspect a stale cache or leftover global symlink shadowing the project version, remove the global install and runner cache, then reinstall:
bunx/npx keep their own download caches; appending @latest forces a fresh fetch instead of 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

The smithers skill (for Claude Code, Codex, and other agents that drive Smithers, not a GUI you click) makes it fluent without reading the whole docs site first, so you reach the aha moment faster. init auto-installs the curated Smithers skill into agents whose skill directory Smithers can write today: Claude Code and Pi (no mkdir, no curl). Other agents: use the MCP server plus standing instructions, or point them at docs-full (below). To sync the generated Smithers CLI command skill set:
That writes generated command-level skill files to supported skill locations, including the canonical ~/.agents/skills directory, and supports --no-global for project-scoped installs, but unlike mcp add, has no --agent target filter. The curated onboarding skill ships the full docs bundle (llms-full.txt) next to its SKILL.md, so agents read the exact API on demand. Once wired in, ask for the outcome, e.g. “orchestrate an agent to add rate limiting and keep iterating until the tests pass,” and it reaches for Smithers itself. Agents without a skills directory: point them at bunx smthrs docs-full (prints the same bundle) or bunx smthrs ask "<question>". Agent Support covers installing skills where supported and registering the MCP server, across 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, or Node >= 22.15
  • 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.

​
Runtime

Bun is the recommended runtime and the one every example assumes. Node runs the library, the CLI, and the gateway too, with two limits: the sqlite backend needs Bun (use SMITHERS_BACKEND=pglite or postgres), and gateway custom-UI bundling needs Bun. See Node runtime for the full contract.

​
Version control

Smithers bundles jj: the optional @smthrs/jj-<platform> package vendors a jj binary per platform, so a fresh install needs no system jj. Resolution order:
  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 is installed (unsupported platform, or --no-optional) and neither jj nor git is on PATH, worktree-needing runs fail with a message to install one. Check what Smithers found with bunx smthrs 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/@smthrs/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 with 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.