Build AI agents with React - Declarative JSX for Claude orchestration
npm install smithers-orchestrator
Ralph the plan, not the agent.
Status: Alpha - not ready for production use.
Your orchestrating agent writes React code that spawns and controls other agents. Let your agents write agents.
Used to orchestrate coding agents that run for days, ship PRs autonomously, and self-heal when they fail.
``tsx
#!/usr/bin/env smithers
import {
createSmithersRoot,
createSmithersDB,
SmithersProvider,
Claude,
} from "smithers-orchestrator";
const db = createSmithersDB({ path: ".smithers/demo.db" });
const executionId = db.execution.start("Demo", "demo.tsx");
function Demo() {
return (
Fix the failing tests in this repository.
);
}
const root = createSmithersRoot();
await root.mount(Demo);
await db.close();
`
Run it and monitor the execution frame by frame:
`bash`
smithers demo.tsx
Smithers is a React framework for coding agents. Write the plan in any coding harness, then monitor your agents as they execute it. The plan is a mix of hardcoded logic and agent output that evolves reactively.
By evolving a declarative plan rather than wiring up every agent interaction, Smithers excels at:
1. One-time agents that accomplish a task and discard
2. Long-running agents that run for days or weeks
---
You program the plan, not the agents. The plan is real executable code: React components that declare what should happen.
| Other Frameworks | Smithers |
| -------------------- | -------------------------- |
| agent.do_step_1() | |agent.do_step_2()
| | |if failed: retry()
| | |
The plan is declarative. Plans evolve in an easy-to-understand way over time, and if the plan breaks for any reason, your monitoring agent can edit the code and restart.
What renders is the current state of the multi-agent setup as readable XML, with SQLite durably persisting state.
Each iteration:
1. Render React to execution plan
2. Execute runnable agents
3. Agent output updates state
4. State change triggers re-render
5. Loop until done
The plan runs as deterministic code, but agents can read it to understand the larger context they're operating within.
Ralph (the autonomous agent loop pattern) handles the render cycle, allowing the plan to run and evolve indefinitely. React handles the diffing.
---
LLMs and humans perform well writing declarative React code. All coding agents can one-shot valid Smithers workflows naturally.
Most multi-agent frameworks fail. They add coordination overhead that costs more than it saves, and you end up worse than a simple while loop. Smithers avoids this by making the plan declarative and the state durable. React's functional nature makes even complex multiagent setups easy to modularize and easy to reason about.
React has a rich ecosystem that works well with agents: Zustand, React Query, and reactive versions of most libraries plug directly into React's reactivity system. This lets you compose declarative plans from battle-tested primitives.
React gives you:
- Composition and reuse
- Version control diffs that make sense
- Agent-generated code you can review
- A massive ecosystem of reactive hooks to reuse
React Hook Compatibility: All TanStack AI and Vercel AI SDK React hooks work in Smithers components.
---
`tsx`
`tsx`
`tsx
const ReviewSchema = z.object({
approved: z.boolean(),
issues: z.array(z.string()),
});
// result.structured: { approved: boolean, issues: string[] }
`
`tsx`
---
State lives in SQLite. Survives restarts.
`tsx
// Set state
db.state.set("phase", "review");
// Get state
const phase = db.state.get("phase");
// Resume after crash
const incomplete = db.execution.findIncomplete();
if (incomplete) {
executionId = incomplete.id;
}
`
---
The React tree is the observability. What you write is what gets logged.
`tsx`
...
...
SQLite stores every frame. Use version control to rewind.
---
`bash`
bun add -g smithers-orchestrator
This installs the smithers CLI globally. Requires Bun 1.0+.
Or install the Claude Code plugin:
`
/plugin add evmts/smithers
---
North Star: SuperSmithers: A meta-agent that watches your agents and rewrites their code to optimize. The architecture is ready. Coming soon.
---