> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install smithers-orchestrator with the workflow pack, or manually for standalone JSX workflow projects.
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](#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 `.
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`](https://www.npmjs.com/package/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 ` 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.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bun add -g smithers-orchestrator@latest # bun
npm install -g smithers-orchestrator@latest # npm
pnpm add -g smithers-orchestrator@latest # pnpm
yarn global add smithers-orchestrator@latest # yarn
```
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):
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
smithers update # detect the install method and upgrade
smithers update --check # just report current vs latest, never change anything
smithers update --dry-run # print the upgrade command without running it
```
Verify the installed version any time with:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
smithers --version
```
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](/reference/sota-models) 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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm rm -g smithers-orchestrator # or: bun remove -g smithers-orchestrator
which smithers # confirm no stale binary remains on PATH
bunx smithers-orchestrator@latest --version
```
`bunx`/`npx` keep their own download caches; appending `@latest` forces them to fetch the newest version rather than reuse a cached one.
## Recommended: Install the Workflow Pack
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator init
```
That scaffolds `.smithers/` with files such as:
| Directory / File | Contents |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.smithers/workflows/` | Public `create-workflow`, `create-skill`, and `docs-driven-development`, plus hidden system `init`, `post-failure`, and `upgrade` |
| `.smithers/prompts/` | Prompt templates required by the curated authoring workflows |
| `.smithers/lib/ddd/` | Portable helpers for the docs-driven-development workflow |
| `.smithers/ui/` | Workflow-owned UIs and their complete local module closure |
| `.smithers/package.json` | Local workflow project manifest with `smithers-orchestrator` dependency |
| `.smithers/tsconfig.json` | TypeScript config for JSX workflow authoring |
| `.smithers/bunfig.toml` | Bun preload config for MDX workflow prompts |
| `.smithers/preload.ts` | Registers the MDX preload plugin |
| `.smithers/agents/` | User-owned agent config (`claude-code.ts`, `codex.ts`, `opencode.ts`, `antigravity.ts`, `index.ts`), edit to pin models/cwd/systemPrompt; preserved across re-inits |
| `.smithers/agents.ts` | Auto-detected agent configuration (regenerated on each `init`) |
| `.smithers/smithers.config.ts` | Repo-level config (lint, test, coverage commands) |
| `.smithers/tickets/` | Ticket workspace used by ticket-oriented workflows |
| `.smithers/executions/` | Execution artifacts directory preserved across re-inits |
| `.smithers/.gitignore` | Ignore rules for generated workflow state |
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator init --force
```
## 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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bunx smithers-orchestrator skills add
```
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 ""`.
To install skills where supported **and** register the MCP server into coding
agents on your machine, see [Agent Support](/agents/overview). 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](/guides/project-structure) from scratch.
See [JSX Installation](/jsx/overview) for the package list, TypeScript configuration, and optional MDX prompt setup.
## Requirements
* [Bun](https://bun.sh) >= 1.3
* TypeScript >= 5
* Model or provider credentials (e.g. [Anthropic](https://docs.anthropic.com) `ANTHROPIC_API_KEY`)
* A version control system for snapshotting and isolating agent work: [jj (Jujutsu)](https://github.com/jj-vcs/jj) or [git](https://git-scm.com). jj is preferred and powers durability, time-travel, and per-task worktrees.
### Version control
Smithers bundles jj. The optional `@smithers-orchestrator/jj-` 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
Run a seeded workflow immediately.
Wire Smithers into your agent and grab a copy-paste setup prompt.
Make your coding agent fluent in Smithers.
The operational command cheatsheet.
Manual TSX authoring setup.
How a standalone workflow project fits together.
The built-in tool sandbox.