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.
Always Run with bunx
Every CLI invocation in these docs is bunx smithers-orchestrator <command>. Do not install Smithers globally and do not use the bare smithers or bunx smithers shorthand.
bunx resolves the package locally if your project depends on it, otherwise it pulls and runs the latest published version.- The published npm package is
smithers-orchestrator. The bare name smithers is a different package, so bunx smithers runs something else entirely.
- A global install creates version-drift problems across machines, CI, and contributors. With
bunx, every project pins Smithers through its own package.json.
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
bunx smithers-orchestrator init
.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.ts | Auto-detected agent configuration |
.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 |
bunx smithers-orchestrator init --force
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)
Desktop App (macOS)
The Smithers desktop GUI is a separate download. It’s a native macOS app (Apple Silicon) that includes the orchestrator, an embedded terminal, and workflow tooling.
Download SmithersGUI.dmg
Or from the terminal:
curl -LO https://get.smithers.sh/SmithersGUI.dmg
open SmithersGUI.dmg
The current build is unsigned. The first time you open it, right-click the app and choose Open, then confirm the Gatekeeper dialog. This only needs to be done once.
After Installation