Skip to main content

​
Smithers Subagent

The <Smithers> component spawns a new Smithers instance to plan and execute complex subtasks. It uses a planner model to generate the orchestration script and an execution model to run the agents.
Experimental. Nested orchestration using a planner model to generate scripts. API may change.

​
Basic Usage

import { Smithers } from "smithers-orchestrator";

<Smithers
  plannerModel="opus"
  executionModel="sonnet"
  onFinished={(result) => console.log(result.output)}
>
  Create a comprehensive test suite for the authentication module.
  Include unit tests, integration tests, and edge cases.
</Smithers>

​
Props

​
plannerModel
'opus' | 'sonnet' | 'haiku'
default:"sonnet"
Model used to plan/generate the orchestration script.
<Smithers plannerModel="opus">
  Complex task requiring careful planning.
</Smithers>
​
executionModel
'opus' | 'sonnet' | 'haiku'
default:"sonnet"
Model used by agents in the generated script.
<Smithers plannerModel="opus" executionModel="sonnet">
  Plan with Opus, execute with Sonnet.
</Smithers>
​
maxPlanningTurns
number
default:"5"
Maximum turns for the planning phase.
​
timeout
number
Timeout in milliseconds for the entire subagent execution.
<Smithers timeout={600000}>  {/* 10 minutes */}
  Time-limited task.
</Smithers>
​
context
string
Additional context to provide to the planner.
<Smithers
  context="This is a Next.js project using Prisma ORM"
>
  Add user profile editing.
</Smithers>
​
cwd
string
Working directory for the subagent.
<Smithers cwd="/path/to/subproject">
  Work in the subproject.
</Smithers>
​
keepScript
boolean
default:"false"
Keep the generated script for debugging.
<Smithers keepScript>
  Task (script will be saved).
</Smithers>
​
scriptPath
string
Custom path for the generated script.
<Smithers keepScript scriptPath="./debug/generated-workflow.tsx">
  Task with custom script path.
</Smithers>
​
reportingEnabled
boolean
default:"true"
Enable progress reporting to database.

​
Callbacks

​
onFinished
(result: SmithersResult) => void
Called when the subagent completes.
​
onError
(error: Error) => void
Called on execution error.
​
onProgress
(message: string) => void
Called with progress updates.
​
onScriptGenerated
(script: string, path: string) => void
Called when the planning phase generates the script.
<Smithers
  onScriptGenerated={(script, path) => {
    console.log("Generated script:", path);
    console.log(script);
  }}
>
  Plan and execute.
</Smithers>

​
How It Works

The Smithers subagent operates in two phases: 
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Planning (plannerModel)                           │
│                                                             │
│  Claude (Opus) analyzes the task and generates a            │
│  Smithers orchestration script (TSX/JSX)                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Execution (executionModel)                        │
│                                                             │
│  The generated script is executed, with <Claude>            │
│  components using the executionModel                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

​
Complex Task Example

<Smithers
  plannerModel="opus"
  executionModel="sonnet"
  timeout={1800000}  // 30 minutes
  keepScript
  context={`
    This is a TypeScript monorepo with:
    - packages/core: Core business logic
    - packages/api: REST API server
    - packages/web: React frontend
    Testing uses Jest with coverage requirements.
  `}
  onScriptGenerated={(script, path) => {
    db.vcs.addReport({
      type: "progress",
      severity: "info",
      title: `Script Generated: ${path}`,
      content: script,
    });
  }}
  onFinished={(result) => {
    console.log("Subagent completed");
    console.log(`Tokens used: ${result.tokensUsed.input + result.tokensUsed.output}`);
  }}
>
  Implement a new user notification system:
  1. Add a notifications table to the database
  2. Create CRUD API endpoints
  3. Add real-time WebSocket updates
  4. Build a notification dropdown in the UI
  5. Write comprehensive tests for all layers
</Smithers>

​
Generated Script Example

The planner might generate something like: 
// Auto-generated by Smithers planner
import {
  createSmithersRoot,
  createSmithersDB,
  SmithersProvider,
  Phase,
  Step,
  Claude,
} from "smithers-orchestrator";

const db = await createSmithersDB({ path: ".smithers/notifications" });
const executionId = await db.execution.start("Notifications", "notifications.tsx");

function NotificationWorkflow() {
  return (
    <SmithersProvider db={db} executionId={executionId}>
      <Phase name="Database">
        <Step name="schema">
          <Claude model="sonnet" allowedTools={["Edit", "Write", "Bash"]}>
            Create the notifications table migration.
            Run the migration.
          </Claude>
        </Step>
      </Phase>

      <Phase name="API">
        <Step name="endpoints">
          <Claude model="sonnet">
            Implement notification CRUD endpoints.
          </Claude>
        </Step>
      </Phase>

      {/* ... more phases ... */}
    </SmithersProvider>
  );
}

const root = createSmithersRoot();
await root.mount(NotificationWorkflow);
await db.execution.complete(executionId);
await db.close();

​
Debugging Generated Scripts

Use keepScript to inspect what was generated: 
<Smithers
  keepScript
  scriptPath="./.smithers/debug/last-script.tsx"
  onError={(err) => {
    console.error("Script failed:", err);
    // The script is at ./.smithers/debug/last-script.tsx
  }}
>
  Complex task.
</Smithers>

​
Nested Subagents

Subagents can spawn their own subagents: 
<Smithers plannerModel="opus" executionModel="sonnet">
  Implement the feature. If you encounter a complex subtask,
  you may spawn additional Smithers subagents to handle it.
</Smithers>

​
Progress Tracking

Monitor subagent progress: 
<Smithers
  onProgress={(msg) => {
    console.log(msg);
    // "Planning task..."
    // "Generated script with 5 phases"
    // "Starting Phase: Database"
    // "Completed Phase: Database"
    // ...
  }}
  onFinished={(result) => {
    console.log(`Duration: ${result.durationMs}ms`);
    console.log(`Agents run: ${result.agentsRun}`);
  }}
>
  Multi-phase task.
</Smithers>

​
Best Practices

The planner benefits from stronger reasoning:
<Smithers plannerModel="opus" executionModel="sonnet">
Help the planner understand your project:
<Smithers context="TypeScript monorepo, Jest tests, PostgreSQL">
Complex tasks need time:
<Smithers timeout={1800000}>  {/* 30 min */}
Inspect generated scripts when things go wrong:
<Smithers keepScript scriptPath="./debug/script.tsx">

Claude Component

Core agent component

SmithersProvider

Top-level workflow control