---
title: Installation
description: 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, seeded workflows, prompts, and agent configuration instead of asking you to assemble the project structure by hand.

All commands on this page use [`bunx`](https://bun.sh) `smithers-orchestrator ...`. The published npm package is [`smithers-orchestrator`](https://www.npmjs.com/package/smithers-orchestrator), so do not use bare `smithers` or `bunx smithers` for these install commands.

## Recommended: Install the Workflow Pack

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

To overwrite an existing scaffold:

```bash
bunx smithers-orchestrator init --force
```

## When to Use Manual Installation

Use manual installation when you are embedding Smithers into an existing TypeScript codebase and want to author a standalone [workflow project](/guides/project-structure) from scratch.

See [JSX Installation](/jsx/installation) 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`)

## After Installation

Choose the next page based on what you need:

- [Quickstart](/quickstart) to run a seeded workflow immediately.
- [CLI Quickstart](/cli/quickstart) to learn the operational workflow.
- [JSX Installation](/jsx/installation) to set up manual TSX authoring.
- [Project Structure](/guides/project-structure) to understand how a standalone workflow project fits together.
- [Tools Integration](/integrations/tools) to understand the built-in tool sandbox.