DOCSEARCHbyAlgolia
Submit Docs

ralph-loop-agent

repository·main·Indexed 21 days ago

https://github.com/vercel-labs/ralph-loop-agent

A framework for creating continuous, autonomous AI agent loops built on the Vercel AI SDK. It features a nested loop architecture (Outer Loop for iteration management and Inner Loop for tool execution) to enable agents to iteratively work on tasks, verify progress, and receive feedback. The package includes the Ralph CLI for autonomous coding tasks like migrations and refactoring, supporting local directories and GitHub repositories with automatic PR creation via the gh CLI.

Tokens
12.3K
Snippets
39
Records
53
Agent score
73%

What's inside ralph-loop-agent

  1. How Ralph Loop Agent works

    main

    The framework uses a nested loop architecture:

    1. Outer Loop (Ralph): Manages the high-level iteration process. It runs iterations until the task is verified as complete, calls verifyCompletion after each iteration, and handles context management/summarization.
    2. Inner Loop (Tool Loop): Handles the immediate LLM interaction. It executes LLM calls and runs tools until a step limit is reached within a single iteration.

  2. How the Ralph Wiggum technique works

    main

    The Ralph Wiggum technique is a continuous AI agent loop methodology. Unlike standard AI SDK tool loops that stop once the LLM finishes its tool calls, Ralph wraps the process in an outer loop.

    The Workflow:

    1. Inner Loop: The AI SDK tool loop executes (LLM ↔ tools) until the model is finished with its current turn.
    2. Verification: A verifyCompletion function checks if the task is actually accomplished.
    3. Feedback/Iteration: If verification fails, feedback is injected into the context, and the agent starts a new iteration. If verification succeeds, the loop terminates.

    This approach is designed for complex, long-running tasks like migrations or refactors that require verification and persistence.

  3. How Plan Mode (Interactive) works

    main

    If you run the CLI on a local directory without a PROMPT.md file or an inline prompt, it enters Plan Mode.

    In this mode, the AI analyzes your codebase (read-only) to understand the context and generates a structured plan consisting of a Goal and a list of Steps. You can then interact with the agent to:

    • Approve: Start the task execution.
    • Refine: Modify the generated plan.
    • Cancel: Exit the process.

  4. Use the Ralph CLI with local directories

    main

    You can run the CLI against a local project directory using several modes:

    1. Interactive Plan Mode: Runs the agent on a directory without a specific prompt, allowing for interactive guidance.
    2. Specific Prompt: Pass a string as the second argument to define the task.
    3. Prompt File: Pass a path to a markdown file (e.g., ./task.md) as the second argument to define the task.

    Note: The command structure is pnpm cli <path-to-project> [prompt-or-file].

    # Interactive Plan Mode
pnpm cli /path/to/your/project

# With a specific prompt
pnpm cli /path/to/project "Migrate from Jest to Vitest"

# With a prompt file
pnpm cli /path/to/project ./task.md

  6. Quick Start with RalphLoopAgent

    main

    To build an autonomous agent, instantiate RalphLoopAgent with a model, instructions, and tools. Use agent.loop() to run the agent until it satisfies the verifyCompletion condition or hits a stopWhen limit.

    Note: zod is used to define tool parameters.

    import { RalphLoopAgent, iterationCountIs } from 'ralph-loop-agent';
import { tool } from 'ai';
import { z } from 'zod';

const tools = {
  markComplete: tool({
    description: 'Mark the task as complete',
    parameters: z.object({ summary: z.string() }),
    execute: async ({ summary }) => ({ complete: true, summary }),
  }),
};

const agent = new RalphLoopAgent({
  model: 'anthropic/claude-opus-4.5',
  instructions: 'You are a coding assistant. Complete tasks and use markComplete when done.',
  tools,
  stopWhen: iterationCountIs(20),
  verifyCompletion: async ({ result }) => {
    for (const step of result.steps) {
      for (const toolResult of step.toolResults) {
        if (toolResult.toolName === 'markComplete') {
          return { complete: true, reason: 'Task marked complete' };
        }
      }
    }
    return { complete: false, reason: 'Continue working' };
  },
});

const result = await agent.loop({
  prompt: 'Create a hello world function in hello.ts',
});

  7. Use PROMPT.md for task definition

    main

    Instead of passing arguments via the command line, you can define a task by creating a PROMPT.md file directly in the root of your target project. When you run the CLI against that project without additional arguments, it will use the contents of PROMPT.md as the instruction set.

    pnpm cli /path/to/project

  8. Use the Ralph CLI with GitHub repositories

    main

    The CLI can target a GitHub repository directly. When a URL is provided, the agent can clone the repo, execute the task, and create a Pull Request (PR).

    To enable automatic PR creation, ensure the GitHub CLI (gh) is installed and authenticated on your machine.

    pnpm cli https://github.com/owner/repo "Upgrade dependencies"
pnpm cli https://github.com/owner/repo ./task.md

  10. Use the Ralph CLI for local or remote tasks

    main

    The Ralph CLI is an autonomous coding agent designed for long-running tasks like migrations, dependency upgrades, and refactoring. You can run it against a local directory or a GitHub repository.

    Local Directory Usage

    • Interactive Plan Mode: Run without a prompt to enter an AI-powered conversation to define your task.
    • Inline Prompt: Provide a string directly in the command.
    • Prompt File: Provide a path to a markdown file containing your task instructions.

    GitHub Repository Usage

    When providing a GitHub URL, the CLI clones the repo to a local sandbox, executes the task, and uses the gh CLI to create a Pull Request with the changes.

    # Local directory - Interactive Plan Mode
pnpm cli /path/to/project

# Local directory - With an inline prompt
pnpm cli /path/to/project "Migrate from CommonJS to ESM"

# Local directory - With a prompt file
pnpm cli /path/to/project ./my-task.md

# GitHub repo - Clones, runs task, creates PR
pnpm cli https://github.com/owner/repo "Upgrade dependencies to latest"
pnpm cli https://github.com/owner/repo ./task.md

  12. Configure environment variables for Ralph CLI

    main

    To use the Ralph CLI, you must provide Vercel Sandbox credentials. If you want the agent to create Pull Requests automatically for GitHub repositories, you must also have the GitHub CLI (gh) installed and authenticated.

    Create a .env file in the examples/cli directory with the following keys:

    # Vercel Sandbox (required)
SANDBOX_VERCEL_TOKEN=your_vercel_token
SANDBOX_VERCEL_TEAM_ID=your_team_id
SANDBOX_VERCEL_PROJECT_ID=your_project_id

# Optional: GitHub CLI for PR creation
# Install with: brew install gh
# Authenticate with: gh auth login