### Initialize agent setup

Source: https://smithers.sh/starters

Perform the first-time setup by adding agents to the project.

```bash
bunx smthrs init --add-agents
```

--------------------------------

### Initialize and Start Gateway

Source: https://smithers.sh/reference/server-gateway

Example of instantiating a Gateway with authentication and registering a workflow with a cron schedule.

```ts
import { Gateway } from "smthrs";

const gateway = new Gateway({
  heartbeatMs: 15_000,
  auth: {
    mode: "token",
    tokens: { "operator-token": { role: "operator", scopes: ["*"] } },
  },
});

gateway.register("deploy", deploy, { schedule: "0 8 * * 1-5" });
await gateway.listen({ port: 7331 });
```

--------------------------------

### Install Smithers via Codex Prompt

Source: https://smithers.sh/guide/setup/codex

Provide this instruction to Codex to have the agent perform the setup steps automatically.

```text
Set up Smithers (a durable AI workflow orchestrator) in this repo:
run `bunx smthrs init`, then `bunx smthrs skills add`
and `bunx smthrs mcp add --agent codex`. From now on, use Smithers
for multi-step, long-running, or approval-gated work.
```

--------------------------------

### listen

Source: https://smithers.sh/reference/server-gateway

Starts the gateway server.

```APIDOC
## listen(options?: { port?: number; host?: string; path?: string })

### Description
Starts the gateway server to listen for incoming RPC and WebSocket connections.

### Parameters
- **options** (Object) - Optional - Server configuration.
  - **port** (number) - Optional - Port to listen on (defaults to 7331).
  - **host** (string) - Optional - Host address.
  - **path** (string) - Optional - Unix socket path.
```

--------------------------------

### Verify Smithers Setup

Source: https://smithers.sh/cli/quickstart

Check installation version and validate VCS and workflow pack health.

```bash
bunx smthrs --version          # prints the version you installed
bunx smthrs workflow doctor    # vcs + workflow pack health
bunx smthrs workflow list      # workflows discovered in this repo
```

--------------------------------

### Install provider dependencies

Source: https://smithers.sh/integrations/gcp-sandbox-provider

Install the required Google Cloud SDK packages for Cloud Run and Storage functionality.

```bash
npm install @google-cloud/run @google-cloud/storage
```

--------------------------------

### listen(options)

Source: https://smithers.sh/reference/server-gateway

Starts the server and binds it to the specified port, host, or Unix socket path.

```APIDOC
## listen(options)

### Description
Binds the server to a network interface or Unix socket and starts the scheduler and event bridge.

### Parameters
- **options** (object) - Required
  - **port** (number) - Optional - TCP port to bind (default: 7331).
  - **host** (string) - Optional - Host/interface to bind.
  - **path** (string) - Optional - Unix socket path; when set, port and host are ignored.

### Returns
- **Promise<http.Server>** - Resolves once the server is bound and services have started.
```

--------------------------------

### Automated Setup Prompt

Source: https://smithers.sh/agents/setup

A prompt to be pasted into a shell-capable coding agent to automate the Smithers installation and configuration process.

```text
Set up Smithers (a durable AI workflow orchestrator) in this repo for me.

1. Run `bunx smthrs init` to scaffold `.smithers/`.
2. Sync Smithers skill files where supported and register its MCP server:
   `bunx smthrs skills add`
   `bunx smthrs mcp add`
3. Read `bunx smthrs docs` so you know the CLI verbs and components.
4. Run `bunx smthrs starters` and tell me which workflow fits the
   task I describe next.

From now on, when I ask for multi-step, long-running, or human-in-the-loop work,
use Smithers to orchestrate it instead of doing it inline.
```

--------------------------------

### Install and scaffold Smithers project

Source: https://smithers.sh/guides/tutorial-workflow

Initializes the project structure, installs dependencies, and authenticates the Codex subscription.

```bash
bunx smthrs init
bun add smthrs zod@^4
bun add -d typescript @types/bun
codex login
```

--------------------------------

### Run Workflow Commands

Source: https://smithers.sh/guides/monitoring-logs

Examples of various workflow-related command patterns.

```bash
bunx smthrs workflow WORKFLOW_ID
```

```bash
bunx smthrs workflow.tsx
```

```bash
bunx smthrs chat create
```

--------------------------------

### Start a workflow server via CLI

Source: https://smithers.sh/integrations/serve

Starts a Hono-based HTTP server for the specified workflow on a custom port and host.

```bash
bunx smthrs up workflow.tsx --serve --port 3000 --host 0.0.0.0 --auth-token "$SMITHERS_API_KEY"
```

--------------------------------

### Install Telegram package

Source: https://smithers.sh/integrations/telegram

Install the required package using pnpm.

```sh
pnpm add @smthrs/telegram
```

--------------------------------

### Install Daytona SDK

Source: https://smithers.sh/integrations/daytona-sandbox-provider

Install the optional Daytona SDK dependency required for the provider to function.

```bash
npm install @daytonaio/sdk
```

--------------------------------

### Start Local Development Environment

Source: https://smithers.sh/guides/custom-workflow-ui

Commands to initiate the Gateway and launch the UI for a specific workflow run.

```bash
bunx smthrs up WORKFLOW -d
bunx smthrs ui RUN_ID
```

```bash
bunx smthrs gateway --port 7331
bunx smthrs ui RUN_ID --gateway http://127.0.0.1:7331
```

--------------------------------

### Install Claude Plugins

Source: https://smithers.sh/agents/claude-code

Commands to install and reload plugins within the Claude environment.

```bash
/plugin marketplace add smithersai/smithers
/plugin install smithers@smithersai
/reload-plugins
```

--------------------------------

### Start workflow in serve mode

Source: https://smithers.sh/guides/agent-operating-playbook

Launch a workflow with HTTP, SSE, and metrics support enabled.

```bash
bunx smthrs up workflow.tsx --serve --metrics --port 7331
```

--------------------------------

### Initialize and serve a workflow application

Source: https://smithers.sh/reference/server-gateway

Example of setting up a Smithers workflow app and serving it using Bun.serve.

```ts
import { SmithersDb, createServeApp } from "smthrs";

const abort = new AbortController();
const app = createServeApp({
  workflow,
  adapter: new SmithersDb(workflow.db),
  runId: "RUN_ID",
  abort,
  authToken: process.env.SMITHERS_API_KEY,
});
Bun.serve({ port: 7331, fetch: app.fetch });
```

--------------------------------

### add

Source: https://smithers.sh/guides/debugging

Installs a workflow pack from GitHub, npm, or a local file.

```APIDOC
## add

### Description
Install a workflow pack from GitHub, npm, or a local file.

### Arguments
- **spec** (string) - Required - GitHub npm or file pack spec

### Flags
- **global** (boolean) - Optional - Install in ~/.smithers/packs instead of the local project
- **yes** (boolean) - Optional - Skip trust confirmation
```

--------------------------------

### startServer(opts?: ServerOptions)

Source: https://smithers.sh/reference/server-gateway

Initializes and starts the Smithers HTTP server with the provided configuration options.

```APIDOC
## startServer(opts?: ServerOptions)

### Description
Boots a listening http.Server exposing REST run lifecycle, SSE streams, and approval routes. This function is synchronous and returns the bound server immediately.

### Parameters
#### opts (ServerOptions) - Optional
- **port** (number) - Optional - Port to bind (default: 7331).
- **db** (unknown) - Optional - Database handle. Enables GET /v1/runs and approvals listing when set.
- **authToken** (string) - Optional - Bearer token for every route but /health; falls back to process.env.SMITHERS_API_KEY.
- **maxBodyBytes** (number) - Optional - Maximum accepted request body size (default: 1048576).
- **rootDir** (string) - Optional - Sandbox root workflow paths and tools resolve against.
- **allowNetwork** (boolean) - Optional - Allow network access from the built-in bash tool (default: false).
- **headersTimeout** (number) - Optional - Maximum time (ms) the HTTP parser may take to receive complete request headers (default: 30000).
- **requestTimeout** (number) - Optional - Maximum time (ms) to receive and parse a single request, body included (default: 60000).

### Returns
- **http.Server** (object) - A listening Node http.Server instance.
```

--------------------------------

### Install the native OpenClaw plugin

Source: https://smithers.sh/agents/openclaw

Use the Smithers CLI to automatically install and register the OpenClaw plugin.

```bash
bunx smthrs mcp add --agent openclaw
```

--------------------------------

### Usage of createOpenApiTool

Source: https://smithers.sh/reference/openapi

Example of creating a single tool with authentication options provided.

```ts
const getPet = await createOpenApiTool("./petstore.json", "getPetById", {
  auth: { type: "apiKey", name: "X-API-Key", in: "header", value: KEY },
});
```

--------------------------------

### Good Operator Response Example

Source: https://smithers.sh/guides/agent-operating-playbook

An example of a helpful, context-aware response that provides a clear diagnosis and actionable recommendation.

```text
The run is paused at the deployment approval gate. I inspected the node output:
tests passed, the review approved, and the only remaining action is your
approval to deploy. I recommend approving because the diff is limited to the
rate-limit middleware and the rollback path is unchanged.
```

--------------------------------

### Install Smithers Hermes Integration

Source: https://smithers.sh/guide/setup/hermes

Run these commands to initialize Smithers and install the Hermes plugin with the MCP server.

```bash
bunx smthrs init
bunx smthrs hermes
```

--------------------------------

### Initialize Memory Store with SQLite

Source: https://smithers.sh/concepts/memory

Setup a memory store using a Bun SQLite database and Drizzle ORM.

```ts
import { createMemoryStore } from "smthrs/memory";
import { Database } from "bun:sqlite";
import { drizzle } from "drizzle-orm/bun-sqlite";

const sqlite = new Database("smithers.db");
const db = drizzle(sqlite);
const store = createMemoryStore(db);
const ns = { kind: "workflow" as const, id: "code-review" };
```

--------------------------------

### Launch Interactive TUI

Source: https://smithers.sh/guides/monitoring-logs

Starts the full-screen terminal monitor for workflows or initial setup.

```bash
bunx smthrs up --interactive
```

```bash
bunx smthrs workflow run WORKFLOW_ID --interactive
```

```bash
bunx smthrs init
```

--------------------------------

### Initialize Smithers project

Source: https://smithers.sh/

Run this command to create a hello.mdx workflow and install the smithers skill into your agents.

```bash
$  bunx smthrs init
```

--------------------------------

### Initialize tools for an AI agent

Source: https://smithers.sh/reference/openapi

Example of fetching an OpenAPI spec from a URL and integrating the generated tools into a ToolLoopAgent.

```ts
import { ToolLoopAgent } from "ai";
import { openai } from "@ai-sdk/openai";
import { createOpenApiTools } from "smthrs";

const tools = await createOpenApiTools("https://api.example.com/openapi.json", {
  baseUrl: "https://api.example.com",
  auth: { type: "bearer", token: process.env.API_TOKEN! },
  include: ["listPets", "getPetById"],
});

const agent = new ToolLoopAgent({ model: openai("gpt-5.6-terra"), tools });
```

--------------------------------

### Run the make-workflow-tutorial workflow

Source: https://smithers.sh/workflows/make-workflow-tutorial

Executes the tutorial workflow to begin the recommendation and build process.

```bash
bunx smthrs workflow run make-workflow-tutorial
```

--------------------------------

### Initialize server instance

Source: https://smithers.sh/reference/server-gateway

Example usage of startServer with basic configuration options including port, authentication, and root directory.

```ts
const server = startServer({
  port: 7331,
  authToken: process.env.SMITHERS_API_KEY,
  rootDir: process.cwd(),
});
```

--------------------------------

### GET /events SSE Stream

Source: https://smithers.sh/integrations/serve

Example of the Server-Sent Events stream format for workflow lifecycle events.

```text
event: smithers
data: {"type":"NodeStarted","runId":"run-1234","nodeId":"analyze","iteration":0,"attempt":1}
id: 1

event: smithers
data: {"type":"NodeFinished","runId":"run-1234","nodeId":"analyze","iteration":0,"attempt":1}
id: 2
```

--------------------------------

### Browse starter templates

Source: https://smithers.sh/starters

List all available starter templates from the gallery.

```bash
bunx smthrs starters
```

--------------------------------

### Run the make-workflow-tutorial workflow with a hint

Source: https://smithers.sh/workflows/make-workflow-tutorial

Provides a specific hint to guide the recommendation engine toward a particular goal.

```bash
bunx smthrs workflow run make-workflow-tutorial \
  --input '{"hint":"Find a workflow for release prep and changelog publishing"}'
```

--------------------------------

### Perform a clean reinstall

Source: https://smithers.sh/installation

Remove global installations and verify that no stale binaries remain before fetching the latest version.

```bash
npm rm -g smthrs   # or: bun remove -g smthrs
which smithers                    # confirm no stale binary remains on PATH
bunx smthrs@latest --version
```

--------------------------------

### starters

Source: https://smithers.sh/guides/troubleshooting

Show plain-English starter workflows with copy-paste commands.

```APIDOC
## starters

### Description
Show plain-English starter workflows with copy-paste commands.

### Arguments
- **id** (string) - Optional - Starter ID or alias

### Flags
- **audience** (string) - Optional - Filter by audience such as product, support, or founder
- **goal** (string) - Optional - Filter by goal such as plan, build, debug, or quality
- **workflow** (string) - Optional - Filter by seeded workflow ID
- **tag** (string) - Optional - Filter by starter tag
```

--------------------------------

### Install Hermes Plugin

Source: https://smithers.sh/integrations/hermes

Installs the Smithers plugin for Hermes using the CLI. This command is idempotent and can be used to upgrade existing installations.

```bash
bunx smthrs hermes

# `hermes` is a convenience alias for the generic form:
bunx smthrs mcp add --agent hermes
```

--------------------------------

### Start the MCP Server

Source: https://smithers.sh/integrations/mcp-server

Launch the Smithers MCP server using the CLI.

```bash
bunx smthrs --mcp
```

--------------------------------

### chat-create

Source: https://smithers.sh/guides/debugging

Create and start a one-task auto-hijacked chat run.

```APIDOC
## chat-create

### Description
Create and start a one-task auto-hijacked chat run.

### Flags
- **agent** (enum) - claude-code|codex|antigravity|pi|kimi|amp
- **cwd** (string) - Working directory for the chat session
- **started-by-harness** (string) - Durable self-reported launch harness
- **started-by-session** (string) - Durable self-reported harness session
- **started-by-prompt** (string) - Explicit durable launch context
```

--------------------------------

### Install SDK Dependencies

Source: https://smithers.sh/integrations/custom-ui

Import the necessary gateway client and React hooks from the orchestrator package.

```ts
import { SmithersGatewayClient } from "smithers-orchestrator/gateway-client";
import {
  SmithersGatewayProvider,
  useGatewayRun,
  useGatewayRunEvents,
  useGatewayActions,
} from "smithers-orchestrator/gateway-react";
```

--------------------------------

### List workflows and start a run

Source: https://smithers.sh/integrations/mcp-server

Use these commands to discover available workflows and initiate a new execution run.

```text
> list_workflows {}

{
  "ok": true,
  "data": {
    "workflows": [
      { "id": "bugfix", "displayName": "bugfix", "entryFile": "./workflows/bugfix.tsx", "sourceType": "user" }
    ]
  }
}

> run_workflow { "workflowId": "bugfix", "prompt": "Fix the auth token expiry bug" }

{
  "ok": true,
  "data": {
    "runId": "smi_abc123",
    "launchMode": "background",
    "status": "running",
    ...
  }
}
```

--------------------------------

### Run Workflow in Serve Mode

Source: https://smithers.sh/guides/monitoring-logs

Starts the HTTP application and maintains the process until interrupted.

```bash
up --serve
```

```bash
up --serve --supervise
```

--------------------------------

### Grep Output Example

Source: https://smithers.sh/guides/openapi-tools-quickstart

Shows the expected output format for grep, including file paths and line numbers.

```text
src/auth.ts:15:  if (token.expired()) {
src/auth.ts:42:  validateToken(token);
tests/auth.test.ts:8:  const token = createTestToken();
```

--------------------------------

### Execute aggregateScores example

Source: https://smithers.sh/reference/scorers

Example usage of the aggregateScores function to filter by run ID.

```ts
const stats = await aggregateScores(adapter, { runId: "RUN_ID" });
```

--------------------------------

### Export starters as JSON

Source: https://smithers.sh/starters

Output the starter catalog in JSON format for use by other tools.

```bash
bunx smthrs starters --format json
```

--------------------------------

### Initialize Smithers

Source: https://smithers.sh/agents/claude-code

Automatically installs the curated onboarding skill when Claude Code is detected.

```bash
bunx smthrs init
```

--------------------------------

### Initialize and use MemoryService

Source: https://smithers.sh/reference/memory

Example showing how to provide the memory layer to an Effect program and interact with the MemoryService.

```ts
import { Effect } from "effect";
import { createMemoryLayer, MemoryService } from "smthrs";

const program = Effect.gen(function* () {
  const memory = yield* MemoryService;
  yield* memory.setFact({ kind: "user", id: "u1" }, "tier", "pro");
});

Effect.runPromise(program.pipe(Effect.provide(createMemoryLayer({ db }))));
```

--------------------------------

### Initialize TanStack DB Collections

Source: https://smithers.sh/guides/sync

Setup the QueryClient and Smithers collections to enable live queries in a local workspace.

```ts
import { QueryClient } from "@tanstack/react-query";
import { useLiveQuery } from "@tanstack/react-db";
import { createSmithersCollections } from "smthrs/gateway-client";

const queryClient = new QueryClient();
const collections = createSmithersCollections(
  { kind: "local", apiBaseUrl: "http://127.0.0.1:7331" },
  queryClient,
);

const { data: runs } = useLiveQuery((q) =>
  q.from({ run: collections.runs({ limit: 50 }) }),
);
```

--------------------------------

### Usage of createOpenApiToolsSync

Source: https://smithers.sh/reference/openapi

Example of generating tools from a local JSON file while excluding specific operations.

```ts
const tools = createOpenApiToolsSync("./petstore.json", {
  exclude: ["deletePet"],
});
```

--------------------------------

### Execute runScorersBatch example

Source: https://smithers.sh/reference/scorers

Example usage of the blocking batch scorer execution function.

```ts
const results = await runScorersBatch(
  { quality: { scorer: tone } },
  {
    runId: "RUN_ID",
    nodeId: "NODE_ID",
    iteration: 0,
    attempt: 1,
    input: "Summarize the article.",
    output: "...",
  },
  null,
);
// results.quality?.score
```

--------------------------------

### Manual Setup Commands

Source: https://smithers.sh/agents/setup

Standard commands to manually scaffold the workflow pack, sync skills, and register the MCP server.

```bash
# 1. Scaffold the workflow pack into .smithers/
bunx smthrs init

# 2. Sync every Smithers-owned skill (CLI command skills + the curated skill)
bunx smthrs skills add

# 3. Register Smithers as an MCP server in every detected agent
bunx smthrs mcp add
```

--------------------------------

### Start local observability backend

Source: https://smithers.sh/capabilities/observability

Launch the local OTLP collector, Prometheus, Tempo, Loki, and Grafana stack using the Smithers CLI.

```bash
bunx smthrs observability   # docker compose -f observability/docker-compose.otel.yml
```

--------------------------------

### Install Vercel Sandbox Dependency

Source: https://smithers.sh/integrations/vercel-sandbox-provider

Install the optional @vercel/sandbox dependency required for the provider to function.

```bash
npm install @vercel/sandbox
```

--------------------------------

### Launch UI and Gateway via CLI

Source: https://smithers.sh/guides/custom-workflow-ui

Commands to start the UI development server, either by auto-starting a Gateway or connecting to a manually managed one.

```bash
# Just open the UI. If no Gateway is reachable on the local port, `ui` starts
# one for you and serves workflow-owned <UI> declarations.
bunx smthrs ui                          # picks the most recent run
bunx smthrs ui RUN_ID                   # specific run

# Or run the Gateway yourself (to keep it alive / choose the port), then open:
bunx smthrs gateway --port 7331         # serves every workspace workflow + declared <UI> entries
bunx smthrs ui RUN_ID --gateway http://127.0.0.1:7331   # point ui at it (--no-autostart never spawns one)
```

--------------------------------

### Install Smithers Claude Plugin

Source: https://smithers.sh/integrations/claude-code-plugin

Installs the plugin from a local path using the Claude CLI.

```bash
claude plugin install /path/to/smithers/claude-plugin
```

--------------------------------

### Saga Component Usage Example

Source: https://smithers.sh/components/saga

Demonstrates defining a workflow with sequential steps and their corresponding compensation tasks.

```tsx
<Workflow name="deploy-saga">
  <Saga
    id="deploy"
    steps={[
      {
        id: "create-pr",
        action: <Task id="create-pr" output={outputs.pr} agent={codeAgent}>Create a PR.</Task>,
        compensation: <Task id="close-pr" output={outputs.closePr} agent={codeAgent}>Close the PR.</Task>,
      },
      {
        id: "deploy-staging",
        action: <Task id="deploy-staging" output={outputs.staging} agent={deployAgent}>Deploy staging.</Task>,
        compensation: <Task id="rollback-staging" output={outputs.rollbackStaging} agent={deployAgent}>Rollback staging.</Task>,
      },
    ]}
  />
</Workflow>
```

--------------------------------

### Implement a Kanban Workflow

Source: https://smithers.sh/components/kanban

A complete example demonstrating how to initialize a Kanban board with defined columns, agents, and ticket sources.

```tsx
/** @jsxImportSource smthrs */
import { createSmithers, Kanban, ClaudeCodeAgent } from "smthrs";
import { z } from "zod";

const { Workflow, smithers, outputs } = createSmithers({
  triage: z.object({ note: z.string() }),
  build: z.object({ note: z.string(), done: z.boolean() }),
});

const agent = new ClaudeCodeAgent({ model: "claude-sonnet-5" });

export default smithers(() => (
  <Workflow name="ticket-board">
    <Kanban
      columns={[
        { name: "triage", agent, output: outputs.triage },
        { name: "build", agent, output: outputs.build },
      ]}
      useTickets={() => [{ id: "T-1" }, { id: "T-2" }]}
      maxIterations={2}
    />
  </Workflow>
));
```

--------------------------------

### Unified diff patch example

Source: https://smithers.sh/guides/openapi-tools-quickstart

Example of a unified diff patch format for the edit tool.

```diff
--- a/src/auth.ts
+++ b/src/auth.ts
@@ -10,3 +10,4 @@
   const token = jwt.sign(payload, secret);
+  logger.info("Token issued", { userId: payload.sub });
   return token;
```

--------------------------------

### Start the Smithers HTTP server

Source: https://smithers.sh/integrations/server

Initializes and starts the server instance with database and authentication configuration.

```ts
import { startServer } from "smthrs";
import { drizzle } from "drizzle-orm/bun-sqlite";

const server = startServer({
  port: 7331,
  db: drizzle("./smithers.db"),
  authToken: process.env.SMITHERS_API_KEY,
  rootDir: process.cwd(),
});
```

--------------------------------

### Initialize OpenAIAgent with createHttpTool

Source: https://smithers.sh/reference/agents

Example of integrating an HTTP tool into an OpenAIAgent configuration with default headers.

```ts
const implementer = new OpenAIAgent({
  model: "gpt-5.6-luna",
  tools: {
    http: createHttpTool({
      defaultHeaders: { "user-agent": "smithers" },
    }),
  },
});
```

--------------------------------

### Install Microsandbox dependency

Source: https://smithers.sh/integrations/microsandbox-sandbox-provider

Install the microsandbox package directly if your package manager omits optional dependencies.

```sh
npm install microsandbox@0.6.6
```

--------------------------------

### Run the hello workflow

Source: https://smithers.sh/workflows/hello

Executes the hello workflow with a custom input name using bunx.

```bash
bunx smthrs workflow run hello --input '{"name":"Ada"}'
```

--------------------------------

### Skill Definition and Quick Start

Source: https://smithers.sh/examples/claude-plugin-skill

The SKILL.md file defines the skill's capabilities, allowed tools, and provides initialization commands.

```markdown
---
name: smithers
description: Create and monitor multi-agent AI orchestrations using Smithers framework. Use when user wants to coordinate multiple AI agents, create complex workflows, build agent pipelines, or mentions "smithers", "multi-agent", "orchestration", "workflow", "agent coordination". Strongly recommends plan mode for orchestrations with 3+ phases.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
user-invocable: true
recommend-plan-mode: true
---

# Smithers Orchestrator

## When to Use
- Orchestrate multiple AI agents working together
- Create complex multi-phase workflows
- Build agent pipelines with state management

## Quick Start
1. Initialize: `bunx smthrs init` (installs the `.smithers/` pack: workflows, prompts, and UIs)
2. Edit `.smithers/workflows/*.tsx` (and their `.smithers/prompts/*.mdx`) to define your workflow
3. Run and monitor: `bunx smthrs up <workflow>` then `bunx smthrs monitor`
```

--------------------------------

### Verify PI CLI Installation

Source: https://smithers.sh/integrations/pi-integration

Checks the installed version of the PI CLI to ensure it is available in the system PATH.

```bash
# Verify PI is installed
pi --version
```

--------------------------------

### Scoped Setup Commands

Source: https://smithers.sh/agents/setup

Commands to target specific agents or restrict skill syncing to the local repository.

```bash
bunx smthrs mcp add --agent cursor
bunx smthrs skills add --no-global
```

--------------------------------

### Initialize and use MemoryStore

Source: https://smithers.sh/reference/memory

Demonstrates initializing a MemoryStore with a Drizzle database and performing basic CRUD operations on facts.

```ts
import { createMemoryStore } from "smthrs";
import { Database } from "bun:sqlite";
import { drizzle } from "drizzle-orm/bun-sqlite";

const store = createMemoryStore(drizzle(new Database("smithers.db")));
const ns = { kind: "workflow" as const, id: "code-review" };

await store.setFact(ns, "model", "gpt-4");
const fact = await store.getFact(ns, "model"); // MemoryFact | undefined
const all = await store.listFacts(ns);
```

--------------------------------

### Deploy and Preview Workflow UI

Source: https://smithers.sh/examples/workflow-ui-react

Use the Smithers CLI to deploy the workflow and open the UI bundle in the browser.

```bash
bunx smthrs up demo-react-ui -d
bunx smthrs ui                          # opens the bundle in your browser
```

--------------------------------

### Bad Operator Response Example

Source: https://smithers.sh/guides/agent-operating-playbook

An example of an unhelpful, overly technical response that forces the human to perform manual inspection.

```text
Run smithers inspect and tell me what it says.
```

--------------------------------

### Install OpenClaw Plugin and MCP Server

Source: https://smithers.sh/guide/setup/openclaw

Run these commands to initialize the Smithers plugin and add the OpenClaw MCP server.

```bash
bunx smthrs init
bunx smthrs mcp add --agent openclaw
```

--------------------------------

### Optimizer Workflow Example

Source: https://smithers.sh/components/optimizer

A complete runnable example demonstrating how to integrate the Optimizer within a Smithers workflow using ClaudeCodeAgent.

```tsx
/** @jsxImportSource smthrs */
import { createSmithers, Optimizer, ClaudeCodeAgent } from "smthrs";
import { z } from "zod";

const { Workflow, smithers, outputs } = createSmithers({
  prompt: z.object({ text: z.string() }),
  evaluation: z.object({ score: z.number(), feedback: z.string() }),
});

const agent = new ClaudeCodeAgent({ model: "claude-sonnet-5" });

export default smithers(() => (
  <Workflow name="prompt-optimizer">
    <Optimizer
      generator={agent}
      evaluator={agent}
      generateOutput={outputs.prompt}
      evaluateOutput={outputs.evaluation}
      targetScore={90}
      maxIterations={5}
    >
      Generate a prompt for summarizing legal documents.
    </Optimizer>
  </Workflow>
));
```

--------------------------------

### smithers starters

Source: https://smithers.sh/guides/debugging

Show plain-English starter workflows with copy-paste commands.

```APIDOC
## smithers starters

### Description
Show plain-English starter workflows with copy-paste commands.

### Arguments
- **id** (string) - Optional - Starter ID or alias

### Flags
- **audience** (string) - Optional - Filter by audience such as product, support, or founder
- **goal** (string) - Optional - Filter by goal such as plan, build, debug, or quality
- **workflow** (string) - Optional - Filter by seeded workflow ID
- **tag** (string) - Optional - Filter by starter tag
```

--------------------------------

### Runbook Implementation Example

Source: https://smithers.sh/components/runbook

Demonstrates how to integrate the Runbook component within a workflow, defining a sequence of steps with varying risk levels.

```tsx
export default smithers(() => (
  <Workflow name="deploy-runbook">
    <Runbook
      defaultAgent={ops}
      stepOutput={outputs.stepResult}
      steps={[
        { id: "health-check", command: "curl -f https://api.example.com/health", risk: "safe" },
        { id: "backup-db", command: "pg_dump prod > backup.sql", risk: "risky" },
        { id: "run-migration", command: "npx prisma migrate deploy", risk: "critical" },
        { id: "smoke-test", command: "npm run test:smoke", risk: "safe" },
      ]}
    />
  </Workflow>
));
```

--------------------------------

### Install Smithers Dependencies

Source: https://smithers.sh/jsx/installation

Install the core Smithers package and Zod for schema validation, along with required TypeScript development dependencies.

```bash
bun add smthrs zod
bun add -d typescript @types/react @types/node
```

--------------------------------

### List installed Smithers skills

Source: https://smithers.sh/agents/overview

Reports the status and version of the curated skill alongside command skills, flagging any stale installations.

```bash
bunx smthrs skills list
```

--------------------------------

### Deploy Gateway with Docker Compose

Source: https://smithers.sh/deployment/reference

Starts the Gateway, SQLite database, and Caddy reverse proxy using the provided compose configuration.

```bash
docker compose -f deploy/reference/docker-compose.yml up
```

--------------------------------

### Initialize Smithers Serve App

Source: https://smithers.sh/integrations/serve

Demonstrates how to initialize a Hono-based app using createServeApp and mount it with Bun.serve.

```ts
import { SmithersDb, createServeApp } from "smthrs";

const adapter = new SmithersDb(workflow.db);
const abort = new AbortController();

const app = createServeApp({
  workflow,
  adapter,
  runId,
  abort,
  authToken: "sk-secret",
});

Bun.serve({ port: 3000, fetch: app.fetch });
```

--------------------------------

### remove

Source: https://smithers.sh/guides/debugging

Remove an installed workflow pack.

```APIDOC
## remove

### Description
Remove an installed workflow pack.

### Parameters
#### Arguments
- **name** (string) - Required - Installed pack name

#### Flags
- **global** (boolean) - Optional - Remove from ~/.smithers/packs
```

--------------------------------

### Project CLI Scripts

Source: https://smithers.sh/reference/package-configuration

Available commands for managing package versions, publishing, and sandbox VM lifecycle.

```bash
node scripts/bump.mjs
```

```bash
node scripts/publish.mjs
```

```bash
bun scripts/sandbox.ts up
```

```bash
bun scripts/sandbox.ts down
```

--------------------------------

### POST /v1/runs

Source: https://smithers.sh/integrations/server

Starts or resumes a run.

```APIDOC
## POST /v1/runs

### Description
Starts or resumes a run.

### Method
POST

### Endpoint
/v1/runs
```

--------------------------------

### Example output for skills list

Source: https://smithers.sh/agents/overview

Displays the current status of the curated Smithers skill for different agents.

```text
Curated skill (smithers, bundled v0.30.0):
  ✓ Claude Code  current (v0.30.0)  /Users/you/.claude/skills/smithers
  ✗ Pi           stale              /Users/you/.pi/agent/skills/smithers

Run `smithers skills add` to bring the curated skill up to date.
```

--------------------------------

### GET /v1/api/approvals

Source: https://smithers.sh/guides/sync

Retrieves a list of approvals.

```APIDOC
## GET /v1/api/approvals

### Description
Retrieves a list of approvals.

### Method
GET

### Endpoint
/v1/api/approvals
```

--------------------------------

### GET /v1/api/runs

Source: https://smithers.sh/guides/sync

Retrieves a list of runs.

```APIDOC
## GET /v1/api/runs

### Description
Retrieves a list of runs.

### Method
GET

### Endpoint
/v1/api/runs
```

--------------------------------

### Initialize Smithers Project

Source: https://smithers.sh/cli/quickstart

Scaffold the .smithers directory or browse available workflow templates.

```bash
bunx smthrs init                                       # scaffold .smithers/
bunx smthrs init --template idea-to-tickets            # return a create-workflow starter request
bunx smthrs starters                                   # browse template IDs
```

--------------------------------

### Execute Oneshot Commands

Source: https://smithers.sh/guides/oneshot

Examples of running oneshot with direct goals, goal files, review settings, and status checks.

```bash
bunx smthrs oneshot "add a loading spinner to the login button"
bunx smthrs oneshot --goal-file TICKET.md
bunx smthrs oneshot "fix the flaky retry test" --review on
bunx smthrs oneshot --status        # usable agents, model chain, preferences
```

--------------------------------

### packs.update

Source: https://smithers.sh/guides/debugging

Re-resolve installed packs from their locked specs.

```APIDOC
## packs.update

### Description
Re-resolve installed packs from their locked specs (all packs when no name is given).

### Parameters
#### Arguments
- **name** (string) - Optional - Pack name to update (default: every locked pack)
```

--------------------------------

### run_workflow

Source: https://smithers.sh/integrations/mcp-server

Starts a new execution of a specified workflow.

```APIDOC
## run_workflow

### Description
Initiates a workflow run with a specific ID and prompt.

### Request Body
- **workflowId** (string) - Required - The ID of the workflow to run
- **prompt** (string) - Required - The prompt for the workflow execution

### Response
- **runId** (string) - The ID of the started run
- **status** (string) - The current status of the run
```

--------------------------------

### GET /metrics

Source: https://smithers.sh/integrations/server

Exports server metrics for observability.

```APIDOC
## GET /metrics

### Description
Exports server metrics. Requires SMITHERS_OTEL_ENABLED=1 and an OTLP endpoint configuration.

### Method
GET

### Endpoint
/metrics
```

--------------------------------

### Start local observability stack

Source: https://smithers.sh/guides/agent-trace-otel-verification

Initializes the local observability infrastructure using Docker Compose and waits for services to become healthy.

```bash
docker compose -f observability/docker-compose.otel.yml up -d
scripts/obs-wait-healthy.sh
```

--------------------------------

### GET /events

Source: https://smithers.sh/integrations/serve

Streams events from the running workflow.

```APIDOC
## GET /events

### Description
Streams events from the workflow in real-time.

### Method
GET

### Endpoint
/events

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token (sk-secret)
```

--------------------------------

### Initialize new workflow

Source: https://smithers.sh/guides/mdx-authoring

Use the built-in create-workflow command to scaffold a new project.

```bash
bunx smthrs workflow run create-workflow
```

--------------------------------

### GET /metrics

Source: https://smithers.sh/integrations/serve

Exposes Prometheus metrics for the workflow.

```APIDOC
## GET /metrics

### Description
Exposes Prometheus metrics for the workflow.

### Method
GET

### Endpoint
/metrics
```

--------------------------------

### GET /frames

Source: https://smithers.sh/integrations/serve

Retrieves rendered workflow frames.

```APIDOC
## GET /frames

### Description
Retrieves rendered workflow frames.

### Method
GET

### Endpoint
/frames

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Max frames (default: 50).
- **afterFrameNo** (number) - Optional - Frames after this number.
```

--------------------------------

### Server configuration options

Source: https://smithers.sh/integrations/server

Defines the available configuration parameters for the startServer function.

```ts
type ServerOptions = {
  port?: number;              // default 7331
  host?: string;              // default 127.0.0.1; a non-loopback bind requires authToken
  db?: unknown;               // enables GET /v1/runs and approvals listing
  authToken?: string;         // falls back to process.env.SMITHERS_API_KEY
  insecure?: boolean;         // default false; allow a non-loopback bind with no authToken (dangerous)
  maxBodyBytes?: number;      // default 1_048_576
  rootDir?: string;           // sandbox root for workflow paths and tools
  allowNetwork?: boolean;     // default false; allows network in `bash`
  integrations?: IntegrationsConfig; // external HMAC-verified integrations served by this process (requires db)
  headersTimeout?: number;    // default 30_000
  requestTimeout?: number;    // default 60_000
};
```

--------------------------------

### update

Source: https://smithers.sh/guides/monitoring-logs

Check for a newer Smithers release and upgrade the install.

```APIDOC
## update

### Description
Check for a newer Smithers release and upgrade the install (or print how).

### Flags
- **check** (boolean) - Optional - Only report current vs latest version; never upgrade
- **dry-run** (boolean) - Optional - Print the upgrade command without running it
```

--------------------------------

### Instantiate Gateway Client

Source: https://smithers.sh/integrations/custom-ui

Initialize the client with configuration options. The baseUrl defaults to the current origin if omitted.

```ts
import { SmithersGatewayClient } from "smithers-orchestrator/gateway-client";

const gateway = new SmithersGatewayClient({
  baseUrl: "https://gateway.example.com",
  token: "operator-jwt",
  client: { id: "my-ui", version: "1.0.0", platform: "browser" },
});

const workflows = await gateway.listWorkflows({ filter: { hasUi: true } });
```

--------------------------------

### ask

Source: https://smithers.sh/guides/debugging

Ask a question about Smithers using an installed agent.

```APIDOC
## ask

### Description
Ask a question about Smithers using an installed agent and the Smithers MCP server.

### Parameters
#### Arguments
- **question** (string) - Optional - Question to ask

#### Flags
- **agent** (enum) - Optional - claude|codex|antigravity|kimi|pi
- **list-agents** (boolean) - Optional - List detected agents and exit
- **dump-prompt** (boolean) - Optional - Print generated system prompt and exit
- **tool-surface** (enum) - Optional - semantic|raw
- **no-mcp** (boolean) - Optional - Disable MCP bootstrap and use prompt fallback
- **print-bootstrap** (boolean) - Optional - Print selected bootstrap configuration and exit
```

--------------------------------

### Initialize Provider-Specific Agents

Source: https://smithers.sh/reference/agents

Demonstrates creating instances of OpenAIAgent and AnthropicAgent with custom instructions and stop conditions.

```ts
import { OpenAIAgent, AnthropicAgent, tools } from "smthrs";
import { stepCountIs } from "ai";

const implementer = new OpenAIAgent({
  model: "gpt-5.6-luna",
  tools,
  instructions: "You are a precise implementation agent.",
  stopWhen: stepCountIs(40),
});

// Provider-specific agents remain available as explicit fallbacks.
const fallbackPlanner = new AnthropicAgent({
  model: "claude-fable-5",
  tools,
  instructions: "You are a careful planner.",
  stopWhen: stepCountIs(40),
});
```

--------------------------------

### GET /v1/runs/:runId/frames

Source: https://smithers.sh/integrations/server

Lists render frames for a run.

```APIDOC
## GET /v1/runs/:runId/frames

### Description
Lists render frames for a run.

### Method
GET

### Endpoint
/v1/runs/:runId/frames

### Parameters
#### Path Parameters
- **runId** (string) - Required - The unique identifier of the run.
```

--------------------------------

### GET /v1/runs

Source: https://smithers.sh/integrations/server

Lists runs (requires database configuration).

```APIDOC
## GET /v1/runs

### Description
Lists runs (requires database configuration).

### Method
GET

### Endpoint
/v1/runs
```

--------------------------------

### Gateway Constructor

Source: https://smithers.sh/reference/server-gateway

Initializes a new Gateway instance with optional configuration settings.

```APIDOC
## constructor(options?: GatewayOptions)

### Description
Creates a new Gateway instance to manage workflows and network communication.

### Parameters
- **options** (GatewayOptions) - Optional - Configuration object for the gateway, including authentication, UI settings, and connection limits.
```

--------------------------------

### GET /

Source: https://smithers.sh/integrations/serve

Retrieves the status of the workflow running in serve mode.

```APIDOC
## GET /

### Description
Retrieves the current status of the workflow.

### Method
GET

### Endpoint
/

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token (sk-secret)
```

--------------------------------

### GET /v1/api/stream

Source: https://smithers.sh/guides/sync

Establishes an SSE connection for invalidation events.

```APIDOC
## GET /v1/api/stream

### Description
Establishes an SSE connection for invalidation events. The stream sends 'change' events with sequence numbers and collection names to trigger client-side refetches.

### Method
GET

### Endpoint
/v1/api/stream
```

--------------------------------

### Run Whole Foods Meal Planner Workflow

Source: https://smithers.sh/workflows/whole-foods-meal-planner

Executes the meal planner workflow using bunx with specific household, dietary, and budget constraints.

```bash
bunx smthrs workflow run whole-foods-meal-planner --input '{
  "householdSize": 2,
  "days": 7,
  "dailyCalorieTarget": 2000,
  "budget": 200,
  "maxPrepMinutes": 15,
  "favoriteFoods": "berries, chicken, yogurt",
  "allergiesExclusions": "peanuts",
  "zipCode": "94107"
}'
```

--------------------------------

### GET /v1/api/events

Source: https://smithers.sh/guides/sync

Retrieves events associated with a specific run.

```APIDOC
## GET /v1/api/events

### Description
Retrieves events associated with a specific run.

### Method
GET

### Endpoint
/v1/api/events

### Parameters
#### Query Parameters
- **runId** (string) - Required - The ID of the run to filter events by.
```

--------------------------------

### Runnable ReviewLoop Workflow Example

Source: https://smithers.sh/components/review-loop

Demonstrates a complete implementation of a code review workflow using the ReviewLoop component.

```typescript
/** @jsxImportSource smthrs */
import { createSmithers, ReviewLoop, ClaudeCodeAgent } from "smthrs";
import { z } from "zod";

const { Workflow, smithers, outputs } = createSmithers({
  code: z.object({ diff: z.string() }),
  review: z.object({ approved: z.boolean(), feedback: z.string() }),
});

const agent = new ClaudeCodeAgent({ model: "claude-sonnet-5" });

export default smithers(() => (
  <Workflow name="code-review">
    <ReviewLoop
      producer={agent}
      reviewer={agent}
      produceOutput={outputs.code}
      reviewOutput={outputs.review}
      maxIterations={3}
    >
      Implement a REST API for user authentication with JWT tokens.
    </ReviewLoop>
  </Workflow>
));
```

--------------------------------

### Run the implement workflow

Source: https://smithers.sh/workflows/implement

Executes the implement workflow using bunx with a specific prompt for the desired change.

```bash
bunx smthrs workflow run implement --prompt "Add rate limiting to the API"
```

--------------------------------

### Execute a workflow

Source: https://smithers.sh/quickstart

Start a durable workflow execution by providing a prompt.

```bash
bunx smthrs workflow run create-workflow --prompt "Add a rate-limiting workflow"
```

--------------------------------

### Launch interactive workflow picker

Source: https://smithers.sh/guides/tui

Open the interactive workflow launcher to select and configure workflows.

```bash
bunx smthrs up --interactive
```

```bash
bunx smthrs up
```

--------------------------------

### observability

Source: https://smithers.sh/guides/debugging

Start or stop the local Docker Compose observability stack.

```APIDOC
## observability

### Description
Start or stop the local Docker Compose observability stack.

### Parameters
#### Flags
- **detach** (boolean) - Optional - Run containers in the background
- **down** (boolean) - Optional - Stop and remove the stack
```

--------------------------------

### GET /v1/approvals

Source: https://smithers.sh/integrations/server

Lists pending approvals (requires database configuration).

```APIDOC
## GET /v1/approvals

### Description
Lists pending approvals (requires database configuration).

### Method
GET

### Endpoint
/v1/approvals
```

--------------------------------

### GET /v1/runs/:runId/events

Source: https://smithers.sh/integrations/server

Retrieves an SSE event stream for a run.

```APIDOC
## GET /v1/runs/:runId/events

### Description
Retrieves an SSE event stream for a run.

### Method
GET

### Endpoint
/v1/runs/:runId/events

### Parameters
#### Path Parameters
- **runId** (string) - Required - The unique identifier of the run.
#### Query Parameters
- **afterSeq** (number) - Optional - Sequence number to start events from.
```

--------------------------------

### GET /health

Source: https://smithers.sh/integrations/serve

Checks the health status of the serve mode server.

```APIDOC
## GET /health

### Description
Returns the health status of the server. No authentication required.

### Method
GET

### Endpoint
/health
```

--------------------------------

### Filter starter templates

Source: https://smithers.sh/starters

Filter the list of available starters based on audience, goal, or workflow type.

```bash
bunx smthrs starters --audience product
bunx smthrs starters --goal quality
bunx smthrs starters --workflow create-workflow
```

--------------------------------

### GET /events

Source: https://smithers.sh/integrations/serve

Provides an SSE stream of lifecycle events for the workflow.

```APIDOC
## GET /events

### Description
Provides an SSE stream of lifecycle events for the workflow. Polls every 500ms and auto-closes when the run reaches a terminal state.

### Method
GET

### Endpoint
/events

### Parameters
#### Query Parameters
- **afterSeq** (number) - Optional - Only events after this sequence (default: -1).
```

--------------------------------

### Initialize Smithers project

Source: https://smithers.sh/guides/tui

Run the initialization command to detect agents and set up the project environment.

```bash
bunx smthrs init
```

```bash
bunx smthrs init --yes
```

--------------------------------

### Initialize Smithers and add skills

Source: https://smithers.sh/guide/setup/pi

Use these commands to set up Smithers in the repository and add skills without the full inspector plugin.

```bash
bunx smthrs init
bunx smthrs skills add
```

--------------------------------

### Verify Smithers version

Source: https://smithers.sh/installation

Check the currently installed version of the Smithers CLI.

```bash
smithers --version
```