Skip to main content

​
Ralph Component

Most users should use <SmithersProvider> instead. SmithersProvider is the canonical orchestrator that handles Ralph internally along with database, state management, and lifecycle concerns. Use <Ralph> only for legacy compatibility or when you specifically need the <ralph> element in serialized output.
Deprecated. <Ralph> is a compatibility wrapper and does not control the loop by itself. Pass maxIterations, onIteration, and onComplete to <SmithersProvider> instead.
The <Ralph> component is the internal loop controller that powers Smithers workflows. It manages iteration count and task tracking for workflows that need to loop until completion. SmithersProvider wraps Ralph automatically—this page documents Ralph for advanced users who need direct access.

​
Minimum Viable Ralph

The simplest possible orchestration is just <Ralph> with a <Claude> inside: 
<SmithersProvider db={db} executionId={executionId}>
  <Ralph>
    <Claude>Your prompt here</Claude>
  </Ralph>
</SmithersProvider>
This creates a single-agent loop that runs until Claude completes its task. The <Claude> component handles the LLM call and tool execution internally.

​
Basic Usage

import { SmithersProvider, Ralph } from "smithers-orchestrator";

<SmithersProvider db={db} executionId={executionId} maxIterations={10}>
  <Ralph>
    <Claude onFinished={() => { /* state change triggers re-render */ }}>
      Keep improving until tests pass.
    </Claude>
  </Ralph>
</SmithersProvider>

​
Accessing Iteration Count

You can access the current iteration count via context: 
import { useSmithers } from "smithers-orchestrator";

function MyComponent() {
  const { ralphCount } = useSmithers();

  return <div>Iteration: {ralphCount}</div>;
}

​
Props

​
maxIterations
number
default:"100"
Deprecated on <Ralph>. Configure maxIterations on <SmithersProvider> instead.
​
onIteration
(iteration: number) => void
Deprecated on <Ralph>. Use <SmithersProvider onIteration> instead.
​
onComplete
() => void
Deprecated on <Ralph>. Use <SmithersProvider onComplete> instead.
​
onMaxIterations
() => void
Called when max iterations is reached without completion. Useful for handling timeout scenarios.

SmithersProvider

Start here — the canonical orchestrator for most workflows

Ralph Wiggum Loop

Deep dive into how the execution loop works internally