Binary
Usebunx 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 publishedsmithers-orchestrator package; in the repository they live under packages/smithers/.
| Import path | Entry file | Purpose |
|---|---|---|
smithers-orchestrator | ./src/index.js | Core API: createSmithers, openSmithersBackend, components, runWorkflow, renderMdx, errors |
smithers-orchestrator/gateway | ./src/gateway.js | Gateway server primitives from @smithers-orchestrator/server/gateway |
smithers-orchestrator/gateway-client | ./src/gateway-client.js | Typed client helpers from @smithers-orchestrator/gateway-client |
smithers-orchestrator/gateway-react | ./src/gateway-react.js | React hooks and providers for gateway-backed UIs |
smithers-orchestrator/gateway-ui | ./src/gateway-ui.js | Prebuilt React components for gateway-backed UIs (RunList, RunTree, ApprovalPanel, and more) |
smithers-orchestrator/ui | ./src/ui.js | Shared shadcn-anatomy component library (Button, Card, Dialog, Tabs, StatusPill, and more) styled through the ui-styleguide theme tokens |
smithers-orchestrator/sandbox | ./src/sandbox.js | Sandbox provider contracts, bundles, and execution helpers |
smithers-orchestrator/telegram | ./src/telegram.js | Telegram 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.js | Cloudflare Workers helpers: Sandbox provider, Durable Object SQLite descriptor, and D1 descriptor |
smithers-orchestrator/daytona | ./src/daytona.js | Daytona sandbox provider: run child workflows in Daytona workspaces |
smithers-orchestrator/vercel | ./src/vercel.js | Vercel Sandbox provider: run child workflows in Vercel sandboxes |
smithers-orchestrator/aws | ./src/aws.js | AWS sandbox provider: run child workflows on ECS Fargate or CodeBuild with S3 bundle transport |
smithers-orchestrator/gcp | ./src/gcp.js | GCP sandbox provider: run child workflows on Cloud Run Jobs with GCS bundle transport |
smithers-orchestrator/jsx-runtime | ./src/jsx-runtime.js | JSX runtime (auto-resolved by jsxImportSource) |
smithers-orchestrator/jsx-dev-runtime | ./src/jsx-runtime.js | JSX dev runtime (auto-resolved in dev mode) |
smithers-orchestrator/tools | ./src/tools.js | Tool sandbox: defineTool, read, grep, bash, edit, write |
smithers-orchestrator/testing | ./src/testing.js | Workflow test helpers: fakeAgent, renderWorkflow, renderPrompt, and runTask |
smithers-orchestrator/server | ./src/server.js | HTTP server for run management and event streaming |
smithers-orchestrator/observability | ./src/observability.js | OpenTelemetry traces, metrics, and Prometheus integration |
smithers-orchestrator/mdx-plugin | ./src/mdx-plugin.js | Bun preload plugin for .mdx imports |
smithers-orchestrator/dom/renderer | ./src/dom/renderer.js | Internal renderer (advanced use) |
smithers-orchestrator/serve | ./src/serve.js | Single-workflow HTTP server via createServeApp |
smithers-orchestrator/scorers | ./src/scorers.js | Eval scorers: createScorer, llmJudge, aggregateScores |
smithers-orchestrator/memory | ./src/memory.js | Cross-run facts, message history, processors, and metrics |
smithers-orchestrator/openapi | ./src/openapi.js | Generate AI SDK tools from OpenAPI specs |
smithers-orchestrator/control-plane | ./src/control-plane.js | Organization, project, billing, usage, secret-reference, and audit primitives |
smithers-orchestrator/* | ./src/*.js | Wildcard-backed facade wrappers for additional public subpaths |
@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 fromsmithers-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.
| Package | Primary surface | Related docs |
|---|---|---|
smithers-orchestrator | Public facade for workflow authoring, components, agents, tools, server helpers, memory, OpenAPI tools, scorers, and JSX runtime setup | This page, Types |
@smithers-orchestrator/cli | CLI entrypoint, MCP server, local workflow pack, account registry commands, DevTools commands, cron, alerts, and server commands | CLI Overview, MCP Server |
@smithers-orchestrator/cloudflare | Cloudflare Workers integration: Sandbox SDK provider, Durable Object SQLite descriptor, and D1 descriptor | Sandbox, Server |
@smithers-orchestrator/aws | AWS sandbox provider: ECS Fargate and CodeBuild execution with S3 bundle transport | Sandbox, AWS |
@smithers-orchestrator/daytona | Daytona sandbox provider: run child workflows in Daytona workspaces | Sandbox, Daytona |
@smithers-orchestrator/gcp | GCP sandbox provider: Cloud Run Jobs execution with GCS bundle transport | Sandbox, GCP |
@smithers-orchestrator/vercel | Vercel Sandbox provider: run child workflows in Vercel sandboxes | Sandbox, Vercel |
@smithers-orchestrator/accounts | Subscription and API-key account registry helpers: listAccounts, addAccount, removeAccount, getAccount, accountToProviderEnv | CLI Agents |
@smithers-orchestrator/agent-eliza | elizaOS AgentRuntime harness for Smithers; opt-in package that owns the @elizaos/core dependency | SDK Agents |
@smithers-orchestrator/agents | AI SDK and CLI agent adapters, CLI capability reports, agent contracts, and tool capability registry | CLI Agents, SDK Agents |
@smithers-orchestrator/automate-site | Private Cloudflare Worker deployment for the event-triggered durable workflows marketing site | Ecosystem |
@smithers-orchestrator/bug-worker | Private Cloudflare Worker behind bug.smithers.sh that receives smithers bug reports and stores them in KV | CLI Overview |
@smithers-orchestrator/components | JSX workflow components such as Task, Workflow, Approval, Sandbox, Timer, Signal, and control-flow components | Components |
@smithers-orchestrator/control-plane | Durable organization, project, team, billing, usage, secret-reference, and audit primitives for hosted deployments | Control Plane |
@smithers-orchestrator/db | SQLite/Drizzle adapter, table setup, run-state derivation, schema helpers, and output tables | Data Model, Run State |
@smithers-orchestrator/ddd-site | Private Cloudflare Worker deployment for the Docs-Driven Development marketing site | Ecosystem |
@smithers-orchestrator/devtools | Snapshot, tree, diff, node lookup, task collection, and DevTools run-store helpers behind the CLI inspect commands | Debugging, CLI Overview |
@smithers-orchestrator/driver | Runtime driver contracts: RunOptions, RunResult, RunStatus, SmithersCtx, outputs, task runtime, interop, and child process helpers | Run Workflow, Execution Model |
@smithers-orchestrator/electric-proxy | ElectricSQL shape proxy for cloud sync, scoped shape access, rate limits, stripped auth forwarding, and shape metrics | Production Hardening, Gateway |
@smithers-orchestrator/engine | Workflow rendering/execution API: runWorkflow, renderFrame, workflow, Smithers, fragment, signals, and Effect versioning | Render Frame, Run Workflow |
@smithers-orchestrator/errors | Error definitions, known codes, JSON serialization, docs URLs, and type guards | Errors |
@smithers-orchestrator/gateway | Stable Gateway RPC contracts, auth scopes, deployment metadata, and generated OpenAPI schema | Gateway, RPC |
@smithers-orchestrator/gateway-client | Browser/client SDK for Gateway RPC requests and event streams | Gateway |
@smithers-orchestrator/gateway-react | React hooks and root helpers for Gateway-backed UIs | Gateway |
@smithers-orchestrator/gateway-ui | Prebuilt React components for Gateway-backed UIs, built on the gateway-react hooks | Gateway UI Components |
@smithers-orchestrator/graph | Framework-neutral workflow graph model, XML nodes, task descriptors, and graph snapshots | Planner Internals, Types |
@smithers-orchestrator/init-site | Private Cloudflare Worker deployment for the interactive Smithers init wizard and workflow builder marketing site | Ecosystem |
@smithers-orchestrator/integrations | External webhook and polling event sources, cursor storage, signature verification, and delivery helpers for workflow integrations | Integrations, Server |
@smithers-orchestrator/jj-darwin-arm64 | Vendored jj (Jujutsu) binary for darwin-arm64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directly | VCS Guide |
@smithers-orchestrator/jj-darwin-x64 | Vendored jj (Jujutsu) binary for darwin-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directly | VCS Guide |
@smithers-orchestrator/jj-linux-arm64 | Vendored jj (Jujutsu) binary for linux-arm64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directly | VCS Guide |
@smithers-orchestrator/jj-linux-x64 | Vendored jj (Jujutsu) binary for linux-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directly | VCS Guide |
@smithers-orchestrator/jj-win32-x64 | Vendored jj (Jujutsu) binary for win32-x64; auto-installed as an optional dependency of @smithers-orchestrator/vcs, not depended on directly | VCS Guide |
@smithers-orchestrator/memory | Cross-run facts, message history, processors, namespaces, service layer, and metrics | Memory, Memory Quickstart |
@smithers-orchestrator/monitor-site | Private Cloudflare Worker deployment for the full-screen Smithers TUI monitor marketing site | Ecosystem |
@smithers-orchestrator/observability | Event types, logging, tracing, metrics, Prometheus rendering, and runtime observability layers | Events, Event Types |
@smithers-orchestrator/openapi | OpenAPI parsing, operation extraction, AI SDK tool generation, schema conversion, and metrics | OpenAPI Tools, Tools |
@smithers-orchestrator/automate-site | Private Cloudflare Worker deployment for the automation marketing site | Ecosystem |
@smithers-orchestrator/ddd-site | Private Cloudflare Worker deployment for the docs-driven-development marketing site | Ecosystem |
@smithers-orchestrator/init-site | Private Cloudflare Worker deployment for the init marketing site | Ecosystem |
@smithers-orchestrator/monitor-site | Private Cloudflare Worker deployment for the monitor marketing site | Ecosystem |
@smithers-orchestrator/openclaw-site | Private Cloudflare Worker deployment for the OpenClaw marketing site | Ecosystem |
@smithers-orchestrator/plugins-site | Private Cloudflare Worker deployment for the plugins marketing site | Ecosystem |
@smithers-orchestrator/self-healing-site | Private Cloudflare Worker deployment for the self-healing marketing site | Ecosystem |
@smithers-orchestrator/telegram-site | Private Cloudflare Worker deployment for the Telegram marketing site | Ecosystem |
@smithers-orchestrator/ui-site | Private Cloudflare Worker deployment for the UI marketing site | Ecosystem |
@smithers-orchestrator/pi-plugin | PI extension runtime, views, API wrappers, and workflow inspection integration | PI Integration |
@smithers-orchestrator/plugins-site | Private Cloudflare Worker deployment for the Smithers plugins marketing site (Claude Code and Codex) | Ecosystem |
@smithers-orchestrator/protocol | Shared contracts, small value types, and protocol-level errors for cross-package use | Types, Errors |
@smithers-orchestrator/react-reconciler | Custom React reconciler, host context, DOM renderer, DevTools preload, driver, and JSX runtime internals | Why React, Render Frame |
@smithers-orchestrator/review | Review CLI package for code review, PR posting, and story-form HTML walkthrough generation, exposed through bunx smithers-orchestrator review and the smithers-review bin | CLI Overview |
@smithers-orchestrator/sandbox | Sandbox bundle, execute, and transport primitives used by the Sandbox component | Sandbox |
@smithers-orchestrator/scheduler | Pure workflow state machine: task state, scheduler decisions, retry/cache policies, wait reasons, and workflow session services | Workflow State, Suspend and Resume |
@smithers-orchestrator/scorers | Scorer definitions, LLM judges, batch execution, aggregation, persistence schema, and metrics | Evals, Evals Quickstart |
@smithers-orchestrator/self-healing-site | Private Cloudflare Worker deployment for the self-healing agent runs marketing site | Ecosystem |
@smithers-orchestrator/server | HTTP, WebSocket, Gateway, cron, webhook, metrics, and single-workflow serving APIs | Server, Serve |
@smithers-orchestrator/smithers-ui | Private local-only UI app: the full run/approval/memory control surface, served by bunx smithers-orchestrator ui --app against a local Gateway | Gateway UI Components |
@smithers-orchestrator/telegram | Telegram Bot API helpers for serverless bots: webhook secret verification, update normalization, typed Bot API calls, retries, MarkdownV2 escaping, chunking, and test fakes | Telegram |
@smithers-orchestrator/telegram-site | Private Cloudflare Worker deployment for the Smithers on Telegram marketing site, including the reference approval Mini App | Telegram, Ecosystem |
@smithers-orchestrator/telegram-summary | Private Cloudflare app: Telegram Bot API ingestion, Kimi daily digests, D1 storage, and the telegram-summary.smithers.sh dashboard | Custom Workflow UI, CLI Overview |
@smithers-orchestrator/testing | Source-shipped workflow test helpers for fake agents, frame rendering, prompt rendering, and descriptor task execution | This page, Render Frame |
@smithers-orchestrator/time-travel | Snapshots, diffs, forks, replay, timelines, VCS tags, rewind locks/audits, and time-travel metrics | Time Travel, Time Travel Quickstart |
@smithers-orchestrator/tool-context | AsyncLocalStorage tool-execution context (run/node/idempotency keys, durability snapshot hook) shared by the engine and smithers-orchestrator without a dependency cycle | Execution Model |
@smithers-orchestrator/tui | Full-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 run | CLI Overview |
@smithers-orchestrator/ui-site | Private Cloudflare Worker deployment for the local Smithers app and AI concierge marketing site | Ecosystem |
@smithers-orchestrator/ui | Shared shadcn-anatomy component library for Smithers UIs: Radix behavior plus CVA variant APIs, styled through the ui-styleguide theme tokens as CSS-in-TS strings | Custom Workflow UI |
@smithers-orchestrator/ui-styleguide | Shared CSS tokens and layout primitives for Smithers browser UIs, including the operator console and workflow UI components | Gateway UI Components, Custom Workflow UI |
@smithers-orchestrator/usage | Account quota and rate-limit usage reporting for Smithers providers | CLI Overview |
@smithers-orchestrator/vcs | VCS discovery and jj workspace operations such as runJj, workspaceAdd, workspaceList, and pointer reverts | VCS Helpers, VCS Guide |
Usage
TypeScript Configuration
JSX Import Source
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 thesmithers-orchestrator monorepo, the root tsconfig.json defines path aliases so source imports resolve without a build step:
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
./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 thereact-dom/servermodule so TypeScript doesn’t error when server-side rendering types are referenced.
@types/react-dom to devDependencies instead of relying on this shim.
Bun Configuration
Runtime Preload
.mdx files can be imported as JSX components at runtime. See MDX Prompts for details.
Test Configuration
| Key | Value | Purpose |
|---|---|---|
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 |
[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 rootpackage.json for development:
| Script | Command | Purpose |
|---|---|---|
typecheck | tsc --noEmit | Type-check the src/ and tests/ trees against tsconfig.json |
typecheck:examples | tsc -p examples/tsconfig.json --noEmit | Type-check example files against a separate config that maps smithers-orchestrator to examples-entry.js |
typecheck:evals | tsc -p evals/tsconfig.json --noEmit | Type-check the agent-fluency eval suite under evals/ against its own config |
lint | node scripts/lint.mjs | Lint package source and tests with oxlint (cross-platform glob expansion) |
lint:fix | node scripts/lint.mjs --fix --fix-suggestions | Apply supported oxlint fixes |
cli | bun run apps/cli/src/index.js | Run the local development CLI entrypoint |
generate:init-pack | bun scripts/generate-workflow-pack.ts | Regenerate the local workflow pack used by bunx smithers-orchestrator init |
sota:gen | bun scripts/generate-sota.ts | Render the SOTA model registry (docs/data/sota-models.json) into its docs page and CLI module |
sota:research | bun scripts/sota-research.ts | Research whether new SOTA models shipped and rewrite the registry if so (used by the daily cron) |
test | node 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 test | Run 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) |
coverage | node scripts/coverage.mjs | Generate a test coverage report across the workspace |
check:effect | node scripts/check-single-effect-version.mjs | Verify the workspace resolves a single Effect version |
check:deps | node scripts/check-dependency-boundaries.mjs | Verify package dependency boundaries |
check:db-access | node scripts/check-no-direct-db-access.mjs | Verify direct run/store DB access remains confined to the tracked issue #470 baseline |
check:docs | node scripts/check-docs.mjs | Verify documentation style and API drift guards |
check:llms | node scripts/check-llms.mjs | Verify generated llms docs are current |
check:sota | node scripts/check-sota.mjs | Verify the SOTA registry’s generated docs page and CLI module match docs/data/sota-models.json |
check:dts | node scripts/check-dts.mjs | Verify per-file .d.ts declarations are freshly regenerated from source |
fetch:jj | node scripts/fetch-jj-binaries.mjs | Fetch vendored jj binaries for supported platforms |
docs:components | node scripts/generate-component-source.mjs | Embed composite component source as tabs in their docs pages |
docs:llms | bun scripts/generate-llms.ts && bun scripts/optimize-llms-full.ts | Regenerate llms-core.txt and llms-full.txt |
docs | cd docs && bunx mintlify dev | Start the Mintlify docs dev server for local preview |
release:content | bunx smithers-orchestrator up .smithers/workflows/release-content.tsx | Run the release-content workflow (changelog, tweet thread, blog) in dry-run mode |
release:content:approve | bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":false}' | Generate release content for real but stop before publishing |
release:content:publish | bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true}' | Generate and publish the release content |
release:workflow | bunx smithers-orchestrator up .smithers/workflows/release.tsx | Run the end-to-end release workflow |
release:workflow:gated | bunx smithers-orchestrator up .smithers/workflows/release.tsx --input '{"requireMarketingContent":true}' | Run the release workflow but require marketing content before publishing |
marketing:thread | bunx 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:write | bunx 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 |
version | node scripts/bump.mjs | Bump package versions using the release helper |
release | node scripts/publish.mjs | Publish packages using the release helper |
sandbox:up | bun scripts/sandbox.ts up | Create a disposable GCP sandbox VM and open an SSH session into it |
sandbox:down | bun scripts/sandbox.ts down | Delete the sandbox VM created by sandbox:up |
For end-user projects
When scaffolding your own project (withbunx smithers-orchestrator init or manually), add a typecheck script:
package.json example.