Skip to main content
TOON is the fastest way to start with Smithers. For pure .toon workflows you only need the Smithers package and the smithers CLI it provides. You do not need React, JSX, or a TypeScript config unless you use run:, handler:, imported schemas, or imported Effect services.

​
Prerequisites

  • Bun >= 1.3
  • SQLite access on the local filesystem

​
Install the Core Package

bun add smithers-orchestrator
That gives you:
  • the TOON loader and compiler
  • the durable runtime
  • the smithers CLI
  • the default SQLite-backed execution flow

​
Create a Project

mkdir my-workflow
cd my-workflow
bun init -y
bun add smithers-orchestrator
Your minimal project can be as small as: 
my-workflow/
  bugfix.toon
  package.json

​
Verify the Install

Create hello.toon: 
name: hello
agents:
  assistant:
    type: claude-code
    model: claude-opus-4-6
    subscription: true
    instructions: You are a concise assistant.

input:
  name: string

steps[1]:
  - id: greet
    agent: assistant
    prompt: "Say hello to {input.name}."
    output:
      message: string
Run it: 
smithers run hello.toon --input '{"name": "World"}'
After the first run, Smithers creates a local smithers.db file and persists the step output there.

​
Optional TypeScript Support

If your TOON workflows import schemas, handlers, or services from TypeScript, add the dependencies those modules use: 
bun add effect @effect/sql
bun add -d typescript
Use this when you want things like:
  • imported Schema.Class or Model.Class definitions
  • handler: functions that run Effect code
  • shared services loaded through imports:

​
Agents in TOON

TOON files declare agents inline using the agents: block. No extra packages are needed — Smithers ships with built-in support for multiple providers (Anthropic, OpenAI, Gemini, and more) through the Vercel AI SDK. 
agents:
  assistant:
    type: anthropic
    model: claude-sonnet-4-20250514
    instructions: You are a concise assistant.
Supported agent types include anthropic, claude-code, openai, gemini, codex, and others. See the TOON Overview for details on declaring agents.

​
Optional TOON Plugins

If you need custom node kinds or additional services, write a local plugin file and import it: 
imports:
  plugins[1]:
    - from: ./my-plugin.ts
      config:
        suffix: "!"
Plugins are loaded when Smithers compiles the .toon file. They can register providers, node kinds, interpolation helpers, and supporting services.

​
Next Steps