Smithers

https://smithers.sh
Admin
Smithers is an open-source, durable runtime for orchestrating AI coding agents with composable,...
Tokens:467,469
Snippets:5,124
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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.
```

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

### 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
```

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

### 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"
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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(),
});
```

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

### Browse starter templates

Source: https://smithers.sh/starters

List all available starter templates from the gallery.

```bash
bunx smthrs starters
```

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

### 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
```

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

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

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

### 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"}'
```

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

### 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 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
```

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

### 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
```

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

### 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",
    ...
  }
}
```

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

### Install Telegram package

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

Install the required package using pnpm.

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

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

### 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 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
```

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

### 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
```

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

### 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" });
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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 });
```

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

### 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 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
```

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

### 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(),
});
```

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

### 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"}'
```

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

### 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
```

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

### 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`
```

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

### 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
```

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

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

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

### 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
```

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

### 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);
```

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

### 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
```

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

### 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
```

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

### 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" };
```

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

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

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

### 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
```

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

### 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
```

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

### 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>
));
```

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

### 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 });
```

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

### 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
```

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

### 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
```

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

### 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 });
```

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

### 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
```

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

### 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
```
Tokens:
Raw