---
title: "Get Started"
icon: "play"
description: "One command. One editable .mdx file. Your first workflow runs in 30 seconds."
---

<Steps>

<Step title="Run one command">

From inside your project:

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

In a terminal, `init` asks exactly one question: which coding agent do you prefer? It shows what it detected (Claude Code, Codex, Pi, ...), you pick one, and it does the rest - scaffolds `.smithers/` into your repo with the default workflow pack, installs its dependencies, adds `smithers.db` to your `.gitignore`, and installs that agent's Smithers plugin (or the skill, if no plugin exists for it). Then it opens a hijacked tutorial session: your chosen agent greets you in your own terminal, narrates what was detected and configured, and walks you through your first runs. Piped or non-interactive callers (CI, agents, `--yes`) skip the question and install the defaults; `--no-tutorial` skips the guided session.

The star of the scaffold is **`.smithers/prompts/hello.mdx`** - your editable hello-world workflow. Open it, change the instruction, and the next run picks it up. No TypeScript required. Re-running `init` later only offers to update files that drifted.

</Step>

<Step title="Make sure your agent knows Smithers">

Your agent drives Smithers, so it needs the Smithers context. Two ways to get it there:

- **Have your agent read the docs.** Ask it to run `bunx smithers-orchestrator docs` (concise index) or `bunx smithers-orchestrator docs-full`, or point it at [`https://smithers.sh/llms-full.txt`](https://smithers.sh/llms-full.txt). Quick, no install.
- **Install the plugin or skill for your harness** so the context is always loaded. Each page below has the exact plugin/skill install:

| Harness | Install the plugin / skill |
|---|---|
| Claude Code | [Claude Code plugin + skill](/agents/claude-code) |
| Codex | [Codex skill + MCP](/agents/codex) |
| Pi | [Pi plugin + skill](/agents/pi) |
| Any other agent | [Set up in your harness](/agents/setup) |

<Note>
`init` already installs the best integration for your preferred agent - the Claude Code plugin, the Hermes/OpenClaw native plugins, or the curated skill for Codex, Pi, OpenCode, Kimi, Amp, and Antigravity. Use the page for your harness above to wire additional agents or add MCP.
</Note>

</Step>

<Step title="Ask your agent to run your hello-world workflow">

You don't run Smithers yourself - your coding agent does. Ask it, in plain language:

> **"Run the hello workflow with Smithers and show me the output."**

Your agent runs `bunx smithers-orchestrator workflow run hello`, a durable run completes, and it reports the output back to you. Edit `.smithers/prompts/hello.mdx`, ask it to run again, watch the output change.

When you run it yourself in a terminal, a cheap, fast model narrates the result: a short recap in the terminal plus a self-contained HTML summary that opens in your browser (written under `.smithers/reports/`). Pass `--no-report`, or set `SMITHERS_NO_REPORT=1`, to skip it.

<Note>
This runs the coding agent `init` detected (Claude Code, Codex, ...), so have one installed and signed in. From here on, your agent drives Smithers for you - you describe outcomes, it picks and runs the workflow.
</Note>

</Step>

<Step title="Ask your agent to open the run UI">

To watch a run live in your browser, ask your agent:

> **"Open the Smithers UI for that run."**

Your agent runs `bunx smithers-orchestrator ui <RUN_ID>`, which opens the run's live status card - stages, output, and any approval gates - in your browser. Keep it open while you hand off more work.

</Step>

</Steps>

## Read next

Your agent ran a workflow. From here, pick by what you need next.

<CardGroup cols={2}>
  <Card title="Talk to your agent" icon="comments" href="/guide/talk-to-your-agent">
    **How-to:** phrase requests so your agent picks the right workflow every time.
  </Card>
  <Card title="Watch and steer" icon="gauge" href="/guide/watch-and-steer">
    **How-to:** follow a live run, clear approvals, and redirect without touching code.
  </Card>
  <Card title="What you can do" icon="list-check" href="/guide/what-you-can-do">
    **Reference:** the full catalog of outcomes you can hand off, and what to say.
  </Card>
  <Card title="The few concepts you need" icon="lightbulb" href="/guide/concepts">
    **Explanation:** the handful of ideas behind durable runs, gates, and loops.
  </Card>
</CardGroup>
