Skip to main content
This page covers: CLI binary usage, subpath export map, TypeScript compiler options, Bun preload and test config, and npm scripts.

Binary

Use bunx smithers-orchestrator <command> for CLI commands. The repository root keeps a private development bin that points at apps/cli/src/index.js; application code should import from the package exports below.

Subpath Exports

Use the subpath form to import only the surface you need. Entry files in this table are relative to the published smithers-orchestrator package; in the repository they live under packages/smithers/.
Import pathEntry filePurpose
smithers-orchestrator./src/index.jsCore API: createSmithers, openSmithersBackend, components, runWorkflow, renderMdx, errors
smithers-orchestrator/gateway./src/gateway.jsGateway server primitives from @smithers-orchestrator/server/gateway
smithers-orchestrator/gateway-client./src/gateway-client.jsTyped client helpers from @smithers-orchestrator/gateway-client
smithers-orchestrator/gateway-react./src/gateway-react.jsReact hooks and providers for gateway-backed UIs
smithers-orchestrator/gateway-ui./src/gateway-ui.jsPrebuilt React components for gateway-backed UIs (RunList, RunTree, ApprovalPanel, and more)
smithers-orchestrator/ui./src/ui.jsShared shadcn-anatomy component library (Button, Card, Dialog, Tabs, StatusPill, and more) styled through the ui-styleguide theme tokens
smithers-orchestrator/sandbox./src/sandbox.jsSandbox provider contracts, bundles, and execution helpers
smithers-orchestrator/telegram./src/telegram.jsTelegram Bot API helpers for serverless bots: webhook secret verification, update normalization, typed Bot API calls, retries, MarkdownV2 escaping, chunking, and test fakes
smithers-orchestrator/cloudflare./src/cloudflare.jsCloudflare Workers helpers: Sandbox provider, Durable Object SQLite descriptor, and D1 descriptor
smithers-orchestrator/daytona./src/daytona.jsDaytona sandbox provider: run child workflows in Daytona workspaces
smithers-orchestrator/vercel./src/vercel.jsVercel Sandbox provider: run child workflows in Vercel sandboxes
smithers-orchestrator/aws./src/aws.jsAWS sandbox provider: run child workflows on ECS Fargate or CodeBuild with S3 bundle transport
smithers-orchestrator/gcp./src/gcp.jsGCP sandbox provider: run child workflows on Cloud Run Jobs with GCS bundle transport
smithers-orchestrator/jsx-runtime./src/jsx-runtime.jsJSX runtime (auto-resolved by jsxImportSource)
smithers-orchestrator/jsx-dev-runtime./src/jsx-runtime.jsJSX dev runtime (auto-resolved in dev mode)
smithers-orchestrator/tools./src/tools.jsTool sandbox: defineTool, read, grep, bash, edit, write
smithers-orchestrator/testing./src/testing.jsWorkflow test helpers: fakeAgent, renderWorkflow, renderPrompt, and runTask
smithers-orchestrator/server./src/server.jsHTTP server for run management and event streaming
smithers-orchestrator/observability./src/observability.jsOpenTelemetry traces, metrics, and Prometheus integration
smithers-orchestrator/mdx-plugin./src/mdx-plugin.jsBun preload plugin for .mdx imports
smithers-orchestrator/dom/renderer./src/dom/renderer.jsInternal renderer (advanced use)
smithers-orchestrator/serve./src/serve.jsSingle-workflow HTTP server via createServeApp
smithers-orchestrator/scorers./src/scorers.jsEval scorers: createScorer, llmJudge, aggregateScores
smithers-orchestrator/memory./src/memory.jsCross-run facts, message history, processors, and metrics
smithers-orchestrator/openapi./src/openapi.jsGenerate AI SDK tools from OpenAPI specs
smithers-orchestrator/control-plane./src/control-plane.jsOrganization, project, billing, usage, secret-reference, and audit primitives
smithers-orchestrator/*./src/*.jsWildcard-backed facade wrappers for additional public subpaths
The PI plugin is published as the separate @smithers-orchestrator/pi-plugin package. The old smithers-orchestrator/pi-plugin and smithers-orchestrator/pi-extension subpaths are no longer exported.

Workspace Packages

Most applications should import from smithers-orchestrator. The workspace packages below are listed for advanced integrations, custom clients, framework development, and monorepo orientation. Some app workspaces are private and are not published packages.
PackagePrimary surfaceRelated docs
smithers-orchestratorPublic facade for workflow authoring, components, agents, tools, server helpers, memory, OpenAPI tools, scorers, and JSX runtime setupThis page, Types
@smithers-orchestrator/cliCLI entrypoint, MCP server, local workflow pack, account registry commands, DevTools commands, cron, alerts, and server commandsCLI Overview, MCP Server
@smithers-orchestrator/cloudflareCloudflare Workers integration: Sandbox SDK provider, Durable Object SQLite descriptor, and D1 descriptorSandbox, Server
@smithers-orchestrator/awsAWS sandbox provider: ECS Fargate and CodeBuild execution with S3 bundle transportSandbox, AWS
@smithers-orchestrator/daytonaDaytona sandbox provider: run child workflows in Daytona workspacesSandbox, Daytona
@smithers-orchestrator/gcpGCP sandbox provider: Cloud Run Jobs execution with GCS bundle transportSandbox, GCP
@smithers-orchestrator/vercelVercel Sandbox provider: run child workflows in Vercel sandboxesSandbox, Vercel
@smithers-orchestrator/accountsSubscription and API-key account registry helpers: listAccounts, addAccount, removeAccount, getAccount, accountToProviderEnvCLI Agents
@smithers-orchestrator/agent-elizaelizaOS AgentRuntime harness for Smithers; opt-in package that owns the @elizaos/core dependencySDK Agents
@smithers-orchestrator/agentsAI SDK and CLI agent adapters, CLI capability reports, agent contracts, and tool capability registryCLI Agents, SDK Agents
@smithers-orchestrator/automate-sitePrivate Cloudflare Worker deployment for the event-triggered durable workflows marketing siteEcosystem
@smithers-orchestrator/bug-workerPrivate Cloudflare Worker behind bug.smithers.sh that receives smithers bug reports and stores them in KVCLI Overview
@smithers-orchestrator/componentsJSX workflow components such as Task, Workflow, Approval, Sandbox, Timer, Signal, and control-flow componentsComponents
@smithers-orchestrator/control-planeDurable organization, project, team, billing, usage, secret-reference, and audit primitives for hosted deploymentsControl Plane
@smithers-orchestrator/dbSQLite/Drizzle adapter, table setup, run-state derivation, schema helpers, and output tablesData Model, Run State
@smithers-orchestrator/ddd-sitePrivate Cloudflare Worker deployment for the Docs-Driven Development marketing siteEcosystem
@smithers-orchestrator/devtoolsSnapshot, tree, diff, node lookup, task collection, and DevTools run-store helpers behind the CLI inspect commandsDebugging, CLI Overview
@smithers-orchestrator/driverRuntime driver contracts: RunOptions, RunResult, RunStatus, SmithersCtx, outputs, task runtime, interop, and child process helpersRun Workflow, Execution Model
@smithers-orchestrator/electric-proxyElectricSQL shape proxy for cloud sync, scoped shape access, rate limits, stripped auth forwarding, and shape metricsProduction Hardening, Gateway
@smithers-orchestrator/engineWorkflow rendering/execution API: runWorkflow, renderFrame, workflow, Smithers, fragment, signals, and Effect versioningRender Frame, Run Workflow
@smithers-orchestrator/errorsError definitions, known codes, JSON serialization, docs URLs, and type guardsErrors
@smithers-orchestrator/gatewayStable Gateway RPC contracts, auth scopes, deployment metadata, and generated OpenAPI schemaGateway, RPC
@smithers-orchestrator/gateway-clientBrowser/client SDK for Gateway RPC requests and event streamsGateway
@smithers-orchestrator/gateway-reactReact hooks and root helpers for Gateway-backed UIsGateway
@smithers-orchestrator/gateway-uiPrebuilt React components for Gateway-backed UIs, built on the gateway-react hooksGateway UI Components
@smithers-orchestrator/graphFramework-neutral workflow graph model, XML nodes, task descriptors, and graph snapshotsPlanner Internals, Types
@smithers-orchestrator/init-sitePrivate Cloudflare Worker deployment for the interactive Smithers init wizard and workflow builder marketing siteEcosystem
@smithers-orchestrator/integrationsExternal webhook and polling event sources, cursor storage, signature verification, and delivery helpers for workflow integrationsIntegrations, Server
@smithers-orchestrator/jj-darwin-arm64Vendored jj (Jujutsu) binary for darwin-arm64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directlyVCS Guide
@smithers-orchestrator/jj-darwin-x64Vendored jj (Jujutsu) binary for darwin-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directlyVCS Guide
@smithers-orchestrator/jj-linux-arm64Vendored jj (Jujutsu) binary for linux-arm64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directlyVCS Guide
@smithers-orchestrator/jj-linux-x64Vendored jj (Jujutsu) binary for linux-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directlyVCS Guide
@smithers-orchestrator/jj-win32-x64Vendored jj (Jujutsu) binary for win32-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directlyVCS Guide
@smithers-orchestrator/memoryCross-run facts, message history, processors, namespaces, service layer, and metricsMemory, Memory Quickstart
@smithers-orchestrator/monitor-sitePrivate Cloudflare Worker deployment for the full-screen Smithers TUI monitor marketing siteEcosystem
@smithers-orchestrator/observabilityEvent types, logging, tracing, metrics, Prometheus rendering, and runtime observability layersEvents, Event Types
@smithers-orchestrator/openapiOpenAPI parsing, operation extraction, AI SDK tool generation, schema conversion, and metricsOpenAPI Tools, Tools
@smithers-orchestrator/automate-sitePrivate Cloudflare Worker deployment for the automation marketing siteEcosystem
@smithers-orchestrator/ddd-sitePrivate Cloudflare Worker deployment for the docs-driven-development marketing siteEcosystem
@smithers-orchestrator/init-sitePrivate Cloudflare Worker deployment for the init marketing siteEcosystem
@smithers-orchestrator/monitor-sitePrivate Cloudflare Worker deployment for the monitor marketing siteEcosystem
@smithers-orchestrator/openclaw-sitePrivate Cloudflare Worker deployment for the OpenClaw marketing siteEcosystem
@smithers-orchestrator/plugins-sitePrivate Cloudflare Worker deployment for the plugins marketing siteEcosystem
@smithers-orchestrator/self-healing-sitePrivate Cloudflare Worker deployment for the self-healing marketing siteEcosystem
@smithers-orchestrator/telegram-sitePrivate Cloudflare Worker deployment for the Telegram marketing siteEcosystem
@smithers-orchestrator/ui-sitePrivate Cloudflare Worker deployment for the UI marketing siteEcosystem
@smithers-orchestrator/pi-pluginPI extension runtime, views, API wrappers, and workflow inspection integrationPI Integration
@smithers-orchestrator/plugins-sitePrivate Cloudflare Worker deployment for the Smithers plugins marketing site (Claude Code and Codex)Ecosystem
@smithers-orchestrator/protocolShared contracts, small value types, and protocol-level errors for cross-package useTypes, Errors
@smithers-orchestrator/react-reconcilerCustom React reconciler, host context, DOM renderer, DevTools preload, driver, and JSX runtime internalsWhy React, Render Frame
@smithers-orchestrator/reviewReview CLI package for code review, PR posting, and story-form HTML walkthrough generation, exposed through bunx smithers-orchestrator review and the smithers-review binCLI Overview
@smithers-orchestrator/sandboxSandbox bundle, execute, and transport primitives used by the Sandbox componentSandbox
@smithers-orchestrator/schedulerPure workflow state machine: task state, scheduler decisions, retry/cache policies, wait reasons, and workflow session servicesWorkflow State, Suspend and Resume
@smithers-orchestrator/scorersScorer definitions, LLM judges, batch execution, aggregation, persistence schema, and metricsEvals, Evals Quickstart
@smithers-orchestrator/self-healing-sitePrivate Cloudflare Worker deployment for the self-healing agent runs marketing siteEcosystem
@smithers-orchestrator/serverHTTP, WebSocket, Gateway, cron, webhook, metrics, and single-workflow serving APIsServer, Serve
@smithers-orchestrator/smithers-uiPrivate local-only UI app: the full run/approval/memory control surface, served by bunx smithers-orchestrator ui --app against a local GatewayGateway UI Components
@smithers-orchestrator/telegramTelegram Bot API helpers for serverless bots: webhook secret verification, update normalization, typed Bot API calls, retries, MarkdownV2 escaping, chunking, and test fakesTelegram
@smithers-orchestrator/telegram-sitePrivate Cloudflare Worker deployment for the Smithers on Telegram marketing site, including the reference approval Mini AppTelegram, Ecosystem
@smithers-orchestrator/telegram-summaryPrivate Cloudflare app: Telegram Bot API ingestion, Kimi daily digests, D1 storage, and the telegram-summary.smithers.sh dashboardCustom Workflow UI, CLI Overview
@smithers-orchestrator/testingSource-shipped workflow test helpers for fake agents, frame rendering, prompt rendering, and descriptor task executionThis page, Render Frame
@smithers-orchestrator/time-travelSnapshots, diffs, forks, replay, timelines, VCS tags, rewind locks/audits, and time-travel metricsTime Travel, Time Travel Quickstart
@smithers-orchestrator/tool-contextAsyncLocalStorage tool-execution context (run/node/idempotency keys, durability snapshot hook) shared by the engine and smithers-orchestrator without a dependency cycleExecution Model
@smithers-orchestrator/tuiFull-screen OpenTUI + React single-run monitor launched by bunx smithers-orchestrator up --interactive; reuses the gateway-react hooks for live tree, graph, logs, timeline, and hijack views of one runCLI Overview
@smithers-orchestrator/ui-sitePrivate Cloudflare Worker deployment for the local Smithers app and AI concierge marketing siteEcosystem
@smithers-orchestrator/uiShared shadcn-anatomy component library for Smithers UIs: Radix behavior plus CVA variant APIs, styled through the ui-styleguide theme tokens as CSS-in-TS stringsCustom Workflow UI
@smithers-orchestrator/ui-styleguideShared CSS tokens and layout primitives for Smithers browser UIs, including the operator console and workflow UI componentsGateway UI Components, Custom Workflow UI
@smithers-orchestrator/usageAccount quota and rate-limit usage reporting for Smithers providersCLI Overview
@smithers-orchestrator/vcsVCS discovery and jj workspace operations such as runJj, workspaceAdd, workspaceList, and pointer revertsVCS Helpers, VCS Guide

Usage

// Core API
import { createSmithers, openSmithersBackend, runWorkflow } from "smithers-orchestrator";

// Tools
import { defineTool, bash, read, write } from "smithers-orchestrator/tools";

// Workflow tests
import { fakeAgent, renderWorkflow } from "smithers-orchestrator/testing";

// Scorers
import { createScorer, llmJudge } from "smithers-orchestrator/scorers";

// MDX plugin (in preload.js)
import { mdxPlugin } from "smithers-orchestrator/mdx-plugin";

// Control-plane primitives
import { ControlPlaneStore } from "smithers-orchestrator/control-plane";

TypeScript Configuration

JSX Import Source

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator"
  }
}
This tells TypeScript to resolve JSX transforms from smithers-orchestrator/jsx-runtime instead of react/jsx-runtime. The Smithers JSX runtime re-exports React’s runtime, so component behavior is identical. This setting enables proper type resolution for Smithers workflow components. See JSX Installation for the complete TypeScript setup.

Path Aliases

When developing inside the smithers-orchestrator monorepo, the root tsconfig.json defines path aliases so source imports resolve without a build step:
"paths": {
  "smithers-orchestrator": ["./packages/smithers/src/index.js"],
  "smithers-orchestrator/jsx-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/jsx-dev-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/tools": ["./packages/smithers/src/tools.js"],
  "smithers-orchestrator/*": [
    "./packages/smithers/src/*.js",
    "./packages/smithers/src/*/index.js"
  ],
  "smithers-orchestrator/scorers": ["./packages/scorers/src/index.js"],
  "@smithers-orchestrator/agents": ["./packages/agents/src/index.js"],
  "@smithers-orchestrator/gateway-client": ["./packages/gateway-client/src/index.ts"],
  "@smithers-orchestrator/gateway-react": ["./packages/gateway-react/src/index.ts"],
  "@smithers-orchestrator/pi-plugin": ["./packages/pi-plugin/src/index.ts"],
  "@smithers-orchestrator/server": ["./packages/server/src/index.js"]
  // The root tsconfig includes the same style of alias for each workspace package.
}
The root package is a private smithers-monorepo; smithers-orchestrator resolves to packages/smithers. End users do not need path aliases, only framework developers do. Installing smithers-orchestrator as a dependency lets Node/Bun module resolution handle import paths automatically.

Local Type Root Shims

"typeRoots": ["./packages/smithers/src/types", "./node_modules/@types"]
The ./packages/smithers/src/types directory contains ambient type declarations that fill gaps in third-party packages. One shim ships today:
  • react-dom-server.d.ts — Declares the react-dom/server module so TypeScript doesn’t error when server-side rendering types are referenced.
End users should add @types/react-dom to devDependencies instead of relying on this shim.

Bun Configuration

Runtime Preload

# bunfig.toml
preload = ["./preload.js"]
The preload script registers the MDX esbuild plugin with Bun’s bundler so .mdx files can be imported as JSX components at runtime. See MDX Prompts for details.

Test Configuration

[test]
root = "."
preload = ["./preload.js"]
KeyValuePurpose
root.Bun discovers test files from the repository root
preload["./preload.js"]Registers the MDX plugin for test files so .mdx imports work in tests
The test preload is separate from the runtime preload. Both point to the same file, but Bun’s [test] section only applies when running bun test. Without it, tests that import .mdx files fail with a module resolution error.

npm Scripts

Defined in the root package.json for development:
ScriptCommandPurpose
typechecktsc --noEmitType-check the src/ and tests/ trees against tsconfig.json
typecheck:examplestsc -p examples/tsconfig.json --noEmitType-check example files against a separate config that maps smithers-orchestrator to examples-entry.js
typecheck:evalstsc -p evals/tsconfig.json --noEmitType-check the agent-fluency eval suite under evals/ against its own config
lintnode scripts/lint.mjsLint package source and tests with oxlint (cross-platform glob expansion)
lint:fixnode scripts/lint.mjs --fix --fix-suggestionsApply supported oxlint fixes
clibun run apps/cli/src/index.jsRun the local development CLI entrypoint
generate:init-packbun scripts/generate-workflow-pack.tsRegenerate the local workflow pack used by bunx smithers-orchestrator init
sota:genbun scripts/generate-sota.tsRender the SOTA model registry (docs/data/sota-models.json) into its docs page and CLI module
sota:researchbun scripts/sota-research.tsResearch whether new SOTA models shipped and rewrite the registry if so (used by the daily cron)
testnode scripts/check-single-effect-version.mjs && node scripts/check-dependency-boundaries.mjs && node scripts/check-no-direct-db-access.mjs && node scripts/check-docs.mjs && node scripts/check-llms.mjs && node scripts/check-sota.mjs && node scripts/check-dts.mjs && node scripts/check-smithers-test-script.mjs && pnpm -r --no-bail testRun docs/config guards, dependency guards, direct DB access guard, llms guards, SOTA registry guard, per-file declaration freshness, and each package test script (no-bail so every failing package is reported)
coveragenode scripts/coverage.mjsGenerate a test coverage report across the workspace
check:effectnode scripts/check-single-effect-version.mjsVerify the workspace resolves a single Effect version
check:depsnode scripts/check-dependency-boundaries.mjsVerify package dependency boundaries
check:db-accessnode scripts/check-no-direct-db-access.mjsVerify direct run/store DB access remains confined to the tracked issue #470 baseline
check:docsnode scripts/check-docs.mjsVerify documentation style and API drift guards
check:llmsnode scripts/check-llms.mjsVerify generated llms docs are current
check:sotanode scripts/check-sota.mjsVerify the SOTA registry’s generated docs page and CLI module match docs/data/sota-models.json
check:dtsnode scripts/check-dts.mjsVerify per-file .d.ts declarations are freshly regenerated from source
fetch:jjnode scripts/fetch-jj-binaries.mjsFetch vendored jj binaries for supported platforms
docs:componentsnode scripts/generate-component-source.mjsEmbed composite component source as tabs in their docs pages
docs:llmsbun scripts/generate-llms.ts && bun scripts/optimize-llms-full.tsRegenerate llms-core.txt and llms-full.txt
docscd docs && bunx mintlify devStart the Mintlify docs dev server for local preview
release:contentbunx smithers-orchestrator up .smithers/workflows/release-content.tsxRun the release-content workflow (changelog, tweet thread, blog) in dry-run mode
release:content:approvebunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":false}'Generate release content for real but stop before publishing
release:content:publishbunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true}'Generate and publish the release content
release:workflowbunx smithers-orchestrator up .smithers/workflows/release.tsxRun the end-to-end release workflow
release:workflow:gatedbunx smithers-orchestrator up .smithers/workflows/release.tsx --input '{"requireMarketingContent":true}'Run the release workflow but require marketing content before publishing
marketing:threadbunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'Generate just the tweet thread in dry-run mode, skipping changelog and blog
marketing:thread:writebunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true,"allowUnreviewedPublish":true,"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"approval":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'Generate and publish just the tweet thread, skipping changelog, blog, and the approval gate
versionnode scripts/bump.mjsBump package versions using the release helper
releasenode scripts/publish.mjsPublish packages using the release helper
sandbox:upbun scripts/sandbox.ts upCreate a disposable GCP sandbox VM and open an SSH session into it
sandbox:downbun scripts/sandbox.ts downDelete the sandbox VM created by sandbox:up

For end-user projects

When scaffolding your own project (with bunx smithers-orchestrator init or manually), add a typecheck script:
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}
See Production Project Structure for a complete user-project package.json example.