Smithers

# Smithers

[![npm version](https://img.shields.io/npm/v/smithers.svg)](https://www.npmjs.com/package/smithers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
[![Bun](https://img.shields.io/badge/Bun-1.0+-black.svg)](https://bun.sh/)

**Declarative JSX framework for building AI agent orchestration workflows.**

I use Smithers for both long-term (weeks) agentic work, as well as one-off scripts.

<!-- TODO: Add GIF demo -->

![Smithers Demo](https://via.placeholder.com/800x400?text=Demo+GIF+Coming+Soon)

---

## Table of Contents

- [Why](#why)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [Usage](#usage)
- [AI SDK React Hooks](#ai-sdk-react-hooks)
- [Recipes](#recipes)
- [Features](#features)
  - [Claude Component](#claude-component)
  - [Ralph Loop Controller](#ralph-loop-controller)
  - [Structured Output with Zod](#structured-output-with-zod)
  - [MCP Tool Integration](#mcp-tool-integration)
  - [Smithers Subagent](#smithers-subagent)
  - [Git/JJ VCS Integration](#gitjj-vcs-integration)
  - [Orchestration Lifecycle](#orchestration-lifecycle)
  - [PhaseRegistry & Step](#phaseregistry--step)
  - [Parallel Execution](#parallel-execution)
  - [Database State Management](#database-state-management)
  - [Rate Limit Monitoring](#rate-limit-monitoring)
- [Contributing](#contributing)

---

## Why

I wanted a tool that allows me to:

- **Write agent workflows as JSX** - because declarative composition is easier to reason about than imperative chains
- **Let Claude Code write the orchestration for me** - I describe what I want, and my agent builds the workflow
- **Persist state across sessions** - pick up where I left off, even days later
- **Mix short scripts with long-running workflows** - same syntax for a quick task or a week-long project
- **See what my agents are doing** - full observability with database logging and reports
- **Use reactive primitives** - React state means my workflows respond to state changes automatically
- **Compose complex behaviors from simple components** - loops, phases, steps, and validation all snap together
- **Keep everything in version control** - workflows are just TypeScript files

---

## Installation

### Install the Smithers Plugin for Claude Code

**Step 1:** Add the Smithers marketplace:

```bash
/plugin marketplace add evmts/smithers
```

**Step 2:** Install the plugin:

```bash
/plugin install smithers@smithers
```

This gives Claude Code the `smithers-orchestrator` skill for creating multi-agent workflows.

### Optional: Install the npm package for programmatic use

If you want to use Smithers components directly in your own scripts:

```bash
bun add smithers-orchestrator
```

---

## Dependencies

### Required

- **[Bun](https://bun.sh/)** - JavaScript runtime (v1.0+)
- **[Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code)** - `bun install -g @anthropic-ai/claude-code`

### Optional

- **[jj (Jujutsu)](https://github.com/martinvonz/jj)** - Alternative VCS with better snapshot support
- **[Codex CLI](https://github.com/openai/codex)** - Used for post-commit code reviews

---

## Usage

### Let Your Agent Write Smithers

**You don't have to write Smithers yourself.** Tell your agent what you want, and it generates the workflow:

```
User: "Create a workflow that monitors my CI, fixes failures automatically, and escalates after 3 failed attempts"

Claude: *generates ci-recovery.tsx*
```

Your agent understands the component model and generates correct, working orchestration scripts.

### State Persistence

All Smithers state is saved in a **SQLite database** on your system that can be easily inspected:

```bash
# View execution history
smithers db executions

# View state for a specific execution
smithers db state --execution-id abc123
```

### Basic Example

```tsx
#!/usr/bin/env bun

import { createSmithersRoot } from "smithers-orchestrator";
import { createSmithersDB } from "smithers-orchestrator/db";
import { SmithersProvider } from "smithers-orchestrator/components/SmithersProvider";
import { Claude } from "smithers-orchestrator/components/Claude";

const db = await createSmithersDB({ path: ".smithers/my-task" });
const executionId = await db.execution.start("My Task", "scripts/my-task.tsx");

async function MyWorkflow() {
  return (
    <SmithersProvider db={db} executionId={executionId}>
      <Claude
        model="sonnet"
        maxTurns={10}
        onFinished={(result) => console.log("Done:", result.output)}
      >
        Analyze this codebase and suggest three improvements.
      </Claude>
    </SmithersProvider>
  );
}

const root = createSmithersRoot();
await root.mount(MyWorkflow);
await db.close();
```

Run it:

```bash
bun my-workflow.tsx
```

---

## AI SDK React Hooks

Smithers re-exports the Vercel AI SDK React hooks so you can import everything
fro

... (truncated)