Smith

Smith is an experimental framework for building inspectable LLM workflows as task trees on disk. Instead of hiding behavior inside framework code, Smith treats folders, markdown files, and sidecars as the program.

The short version: the LLM is the runtime, the filesystem is the programming language, and markdown prompts are the bytecode.

Status: early and still evolving. The core task-tree model is working, but the runtime, built-in modules, and planner workflow are still being sharpened.

If you are deciding whether this is for you, Smith is aimed at people who want:

• File-native LLM workflows that are easy to read, diff, and inspect
• A planner that generates proposals on disk instead of mutating projects implicitly
• A runtime that can mix model-backed tasks, shell tools, and shipped web tools
• A system where prompts, schemas, tool allowlists, and outputs remain first-class files

Start here if you want to try it:

• How to Use Smith for setup and first-run instructions
• Examples for checked-in apps and repo hygiene notes
• Architecture if you want the deeper design story

Mental Model

.NET	Smith
CLR	LLM
IL bytecode	Markdown prompts
BCL / System namespace	Core modules (planner, tool-create)
.exe / application	A task tree (folders + markdown)
MSBuild	The Go runner (bootloader)

The task format is the product. The runner is replaceable.

What A Smith App Looks Like

A Smith app is a folder tree. Each task is a directory with a task.md. The application is not hidden inside framework code — you can open the folder and read the program.

my-app/
  task.md                  # the prompt — what the LLM executes
  agent.md                 # model config (required at root)
  tools.md                 # tool permissions (optional)
  schema.md                # JSON output schema (optional)
  return.md                # two-phase execution (optional)
  context/static/          # reference docs injected into prompt
  tools/                   # app-defined tool definitions
    issue.search/
      tool.yaml
      input.schema.json
      run.sh
  subtasks/
    01-gather/
      task.md
      tools.md             # - issue.search
    02-analyze/
      task.md
      schema.md

Core Capabilities

Task Execution (RFC 0001)

The runner discovers task trees, validates them, builds a dependency graph, assembles prompts, and executes tasks in order. Each task produces output in its output/ directory.

• Static task-tree discovery — folders are control flow, task.md is the code
• Dependency graph — depends_on declares sibling-to-sibling data flow
• Agent inheritance — agent.md config flows from parent to child
• JSON schema validation — schema.md enforces structured output
• Output caching — tasks with unchanged inputs skip re-execution
• Two-phase execution — return.md lets a parent synthesize child outputs into a final result

Proposal-Based Planning (RFC 0002)

Smith plans new task trees from a natural language goal. The planner is itself a Smith application — it receives a goal and produces a proposal: a set of file operations that materialize a valid task tree.

smith plan my-app/ "Build a research pipeline that gathers data and writes a briefing"
smith apply .smith/proposals/<id>/

Proposals are inspectable files on disk. Nothing is applied without explicit smith apply.

Staged Planning & Local Model Routing (RFC 0003)

The planner is a four-stage pipeline that reduces cloud API pressure:

1. Distill — compress project context (can run on local models via Ollama)
2. Design — architect the task tree structure (cloud model)
3. Draft — produce all file contents inline (can run on local models)
4. Review — semantic validation and correction (cloud model)

Each stage is cached independently. Changing the goal invalidates design onward. Changing the project invalidates distill onward. Cheap work (summarization, template expansion) routes to Ollama; expensive work (architecture, review) routes to Claude.

App-Defined Tools (RFC 0004)

Tasks can define their own tools with rich metadata, input schemas, and execution backends.

Shell tools — external integrations via shell scripts:

# tools/issue.search/tool.yaml
description: "Search issues by query"
type: shell
timeout: 15s
env:
  - GITHUB_TOKEN

Shell tools receive JSON on stdin, return JSON on stdout, and run with /bin/sh -e.

Task tools — reusable LLM operations backed by Smith task trees:

# tools/customer.lookup/tool.yaml
description: "Look up customer by ID"
type: task
source: customer-lookup

Task tools execute a referenced task tree as a function call, with isolated invocations, depth tracking, and output mapping.

Tools are data (folder + YAML + JSON Schema), not code. tools.md remains the per-task allowlist — defining a tool does not grant access to it.

Tool-Aware Planning (RFC 0004)

The planner sees existing tool definitions, assigns tools to tasks, and specs new tools as part of a plan. New tool authoring is delegated to a tool-create module that produces tool file bundles — one invocation per tool, each independently cacheable and routable to a code-focused model.

The planner pipeline remains pure (no tool execution during planning). Tool creation is orchestrated post-pipeline:

1. Planner designs tool specs alongside the task tree
2. plan.Plan() runs tool-create once per spec
3. Generated tool files merge into the proposal
4. PreValidate catches structural issues on the merged workspace

Shipped Web Tools (RFC 0005)

Smith also ships a small web tooling library through the normal lib path:

• web.lookup — public web search
• web.fetch — raw page retrieval
• web.fetch_markdown — deterministic readable markdown extraction
• web.summarize — concise structured summaries built on web.fetch_markdown

The first three are native in-process Go tools. web.summarize is the only model-backed web tool in v1, and it requires configured credentials for its fixed anthropic/claude-sonnet-4-6 model via smith config.

Opt in from an app the same way you opt in to any lib tool:

# tools.md
- web.lookup
- web.fetch_markdown

Use web.lookup when you need search results, web.fetch when you need the raw response body, web.fetch_markdown when you want readable page content, and web.summarize when you only need a concise gist.

Examples

• Examples Index — checked-in examples and notes on keeping .smith/ runtime data out of version control

Interactive TUI (RFC 0007)

Running smith with no arguments launches an interactive terminal dashboard (requires a TTY):

smith                         # launches TUI if TTY, otherwise prints help
smith tui                     # explicit alias

The TUI provides four tabs:

• Config — interactive provider setup (API keys, Ollama endpoint), live model discovery, default model selection
• Projects — browse known projects, view run history and status
• Packages — browse installed lib modules and tool definitions with provenance tracking
• Search — cross-project content search

Model Configuration

Smith supports configuring default models for planning and task execution:

smith config                  # interactive config (or use the TUI Config tab)

Config is stored in ~/.smith/config.json:

• default_planner_model — model used for planner stages (e.g. anthropic/claude-sonnet-4-6)
• default_task_model — model injected into planned task trees

CLI

smith                         # launch TUI (TTY) or print help (non-TTY)
smith tui                     # launch TUI explicitly

smith run <path>              # execute a task tree
smith run --dry <path>        # validate and show execution plan
smith run --no-cache <path>   # force re-execution of all tasks
smith run --input key=val     # pass run input

smith plan <path> <goal>      # generate a proposal from a goal
smith plan --model <model>    # override planner model

smith apply <proposal>        # apply a proposal to its target
smith apply --dry <proposal>  # preview without writing

smith validate <path>         # validate against RFC 0001 rules
smith status <path>           # report per-task execution status

smith init                    # initialize Smith libraries
smith lib update              # update built-in libraries
smith config                  # configure credentials

Build and run:

go build ./cmd/smith
smith --help

Project Structure

smith/
  cmd/smith/               # CLI entry point
  internal/
    cli/                   # command implementations
    tui/                   # terminal UI (Bubble Tea)
    task/                  # task tree discovery, parsing, validation
    executor/              # task execution engine
    runtime/               # LLM provider interface (Anthropic, Ollama)
    tools/                 # tool definitions, discovery, handlers
    plan/                  # planning orchestration
    proposal/              # proposal authoring and validation
    validate/              # RFC 0001 validation rules
    prompt/                # prompt assembly
    config/                # user configuration
    modeldisc/             # live model discovery (probe providers)
    projects/              # global project tracking
    run/                   # per-run directories and manifests
    lib/                   # built-in module management
      builtin/
        planner/           # the planner task tree (4-stage pipeline)
        tool-create/       # tool authoring module
  docs/
    ARCHITECTURE.md        # broad system shape
    rfc/
      0001-smith-v1-core.md
      0002-proposal-based-planning.md
      0003-staged-planning.md
      0004-app-defined-tools.md
      0005-web-tools.md
      0006-run-history.md
      0007-smith-tui.md
      0008-robust-planning-and-execution.md
    ideation/              # concept exploration

Read More

• RFC 0001: v1 Core Runtime
• RFC 0002: Proposal-Based Planning
• RFC 0003: Staged Planning & Local Model Routing
• RFC 0004: App-Defined Tools & Tool-Aware Planning
• RFC 0005: Smith-Shipped Web Tools
• RFC 0006: Per-Run Runtime Directories
• RFC 0007: Smith TUI
• RFC 0008: Robust Planning and Trustworthy Task Execution
• Examples Index
• Architecture