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, 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.

Recommended: Install the Workflow Pack

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:

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:

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:

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