> ## Documentation Index
> Fetch the complete documentation index at: https://smithers-feat-claude-workflow-mirror.mintlify.site/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.

<Note>
  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.
</Note>

## Always Run with `bunx`

<Warning>
  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.
</Warning>

* 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`.

## Recommended: Install the Workflow Pack

```bash theme={null}
bunx smithers-orchestrator init
```

That scaffolds `.smithers/` with files such as:

| Directory / File               | Contents                                                                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.smithers/workflows/`         | Pre-built workflows (`implement`, `review`, `plan`, `ralph`, `debug`, ...)                                                                                          |
| `.smithers/prompts/`           | Shared MDX prompt templates                                                                                                                                         |
| `.smithers/components/`        | Reusable TSX components (`Review`, `ValidationLoop`, ...)                                                                                                           |
| `.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                                                                                                                           |

To overwrite an existing scaffold:

```bash theme={null}
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 skill into every coding agent it detects (no `mkdir`, no
`curl`). To install or re-install at any time:

```bash theme={null}
bunx smithers-orchestrator skills add
```

That copies the curated `smithers` skill (SKILL.md + the full docs bundle) into
every detected agent on your machine. Target a single agent with `--agent`:

```bash theme={null}
bunx smithers-orchestrator skills add --agent claude-code
```

The skill ships the full docs bundle (`llms-full.txt`) next to its `SKILL.md`, so
the agent can read the exact API on demand. Once installed, 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 the skill **and** register the MCP server into every coding agent on
your machine at once, see [Agent Support](/agents/overview). It covers Claude
Code, Codex, Cursor, Copilot, Pi, Hermes, OpenClaw, and \~20 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-<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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run a seeded workflow immediately.
  </Card>

  <Card title="Set up in your harness" icon="plug" href="/agents/setup">
    Wire Smithers into your agent and grab a copy-paste setup prompt.
  </Card>

  <Card title="Install the agent skill" icon="robot" href="#install-the-agent-skill">
    Make your coding agent fluent in Smithers.
  </Card>

  <Card title="CLI Quickstart" icon="terminal" href="/cli/quickstart">
    The operational command cheatsheet.
  </Card>

  <Card title="JSX installation" icon="code" href="/jsx/overview">
    Manual TSX authoring setup.
  </Card>

  <Card title="Project structure" icon="folder-tree" href="/guides/project-structure">
    How a standalone workflow project fits together.
  </Card>

  <Card title="Tools integration" icon="screwdriver-wrench" href="/integrations/tools">
    The built-in tool sandbox.
  </Card>
</CardGroup>