Skip to main content
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. 
bunx smithers-orchestrator init
That scaffolds .smithers/ with files such as:
Directory / FileContents
.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.jsonLocal workflow project manifest with smithers-orchestrator dependency
.smithers/tsconfig.jsonTypeScript config for JSX workflow authoring
.smithers/bunfig.tomlBun preload config for MDX workflow prompts
.smithers/preload.tsRegisters 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.tsAuto-detected agent configuration (regenerated on each init)
.smithers/smithers.config.tsRepo-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/.gitignoreIgnore 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. 
mkdir -p ~/.claude/skills/smithers
curl -fsSL https://raw.githubusercontent.com/smithersai/smithers/main/skills/smithers/SKILL.md \
  -o ~/.claude/skills/smithers/SKILL.md
curl -fsSL https://smithers.sh/llms-full.txt \
  -o ~/.claude/skills/smithers/llms-full.txt
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)

​
After Installation