Ralph Loop Agent

ralph-loop-agent

Continuous Autonomy for the AI SDK

Note: This package is experimental. APIs may change between versions.

Packages

Package	Description
ralph-loop-agent	Core agent framework with loop control, stop conditions, and context management

Examples

Example	Description
cli	Full-featured CLI agent with Vercel Sandbox, Playwright, PostgreSQL, and GitHub PR integration

Installation

npm install ralph-loop-agent ai zod

What is the Ralph Wiggum Technique?

The Ralph Wiggum technique is a development methodology built around continuous AI agent loops. At its core, it's elegantly simple: keep feeding an AI agent a task until the job is done. As Geoffrey Huntley describes it: "Ralph is a Bash loop."

Named after the lovably persistent Ralph Wiggum from The Simpsons, this approach embraces iterative improvement over single-shot perfection. Where traditional agentic workflows stop when an LLM finishes calling tools, Ralph keeps going—verifying completion, providing feedback, and running another iteration until the task actually succeeds.

Think of it as while (true) for AI autonomy: the agent works, an evaluator checks the result, and if it's not done, the agent tries again with context from previous attempts.

┌──────────────────────────────────────────────────────┐
│                   Ralph Loop (outer)                 │
│  ┌────────────────────────────────────────────────┐  │
│  │  AI SDK Tool Loop (inner)                      │  │
│  │  LLM ↔ tools ↔ LLM ↔ tools ... until done      │  │
│  └────────────────────────────────────────────────┘  │
│                         ↓                            │
│  verifyCompletion: "Is the TASK actually complete?"  │
│                         ↓                            │
│       No? → Inject feedback → Run another iteration  │
│       Yes? → Return final result                     │
└──────────────────────────────────────────────────────┘

Why Continuous Autonomy?

Standard AI SDK tool loops are great—but they stop as soon as the model finishes its tool calls. That works for simple tasks, but complex work often requires:

• Verification: Did the agent actually accomplish what was asked?
• Persistence: Retry on failure instead of giving up
• Feedback loops: Guide the agent based on real-world checks
• Long-running tasks: Migrations, refactors, multi-file changes

Ralph wraps the AI SDK's generateText in an outer loop that keeps iterating until your verifyCompletion function confirms success—or you hit a safety limit.

Features

• Iterative completion — Runs until verifyCompletion says the task is done
• Full AI SDK compatibility — Uses AI Gateway string format, supports all AI SDK tools
• Flexible stop conditions — Limit by iterations, tokens, or cost
• Context management — Built-in summarization for long-running loops
• Streaming support — Stream the final iteration for responsive UIs
• Feedback injection — Failed verifications can guide the next attempt

Usage

Basic Example

import { RalphLoopAgent, iterationCountIs } from 'ralph-loop-agent';

const agent = new RalphLoopAgent({
  model: 'anthropic/claude-opus-4.5',
  instructions: 'You are a helpful coding assistant.',
  stopWhen: iterationCountIs(10),
  verifyCompletion: async ({ result }) => ({
    complete: result.text.includes('DONE'),
    reason: 'Task completed successfully',
  }),
});

const { text, iterations, completionReason } = await agent.loop({
  prompt: 'Create a function that calculates fibonacci numbers',
});

console.log(text);
console.log(`Completed in ${iterations} iterations`);
console.log(`Reason: ${completionReason}`);

Migration Example

import { RalphLoopAgent, iterationCountIs } from 'ralph-loop-agent';

const migrationAgent = new RalphLoopAgent({
  model: 'anthropic/claude-opus-4.5',
  instructions: `You are migrating a codebase from Jest to Vitest.
    
    Completion criteria:
    - All test files use vitest imports
    - vitest.config.ts exists
    - All tests pass when running 'pnpm test'`,
  
  tools: { readFile, writeFile, execute },
  
  stopWhen: iterationCountIs(50),
  
  verifyCompletion: async () => {
    const checks = await Promise.all([
      fileExists('vitest.config.ts'),
      !await fileExists('jest.config.js'),
      noFilesMatch('**/*.test.ts', /from ['"]@jest/),
      fileContains('package.json', '"vitest"'),
    ]);
    
    return { 
      complete: checks.every(Boolean),
      reason: checks.every(Boolean) ? 'Migration complete' : 'Structural checks failed'
    };
  },

  onIterationStart: ({ iteration }) => console.log(`Starting iteration ${iteration}`),
  onIterationEnd: ({ iteration, duration }) => console.log(`Iteration ${iteration} completed in ${duration}ms`),
});

const result = await migrationAgent.loop({
  prompt: 'Migrate all Jest tests to Vitest.',
});

console.log(result.text);
console.log(result.iterations);
console.log(result.completionReason);

With Tools