GitHub - 0livare/ralph-wiggum-ai: Opinionated implementation of the Ralph Wiggum AI technique

2 min read Original article ↗

Opinionated implementation of the Ralph Wiggum AI technique.

Ralph solves the AI context window problem in the most simplistic way possible; keep feeding new AI sessions the same prompt until the job is done.

"Ralph is a Bash loop." - Geoffrey Huntley

Anthropic's official ralph plugin gets the core principle of Ralph wrong by preventing a single instance of claude from exiting, rather than continuously starting new sessions.

ralph

Installation

Prerequisites

  1. This package depends on Bun being installed globally
  2. Claude Code must be must be installed and configured
# Create a global `ralph` cli command
npm i -g ralph-wiggum-ai

Usage

Create a PRD file

Before setting Ralph to work, you need to create a PRD (product requirements document) prd.json file that defines the tasks for Ralph to perform.

You can generate a PRD in two ways:

Option 1: Generate a sample PRD to manually edit

# Generate a sample prd.json file for you to edit
ralph prd --sample

Option 2: Generate a PRD interactively with Claude Code

# Provide task description inline
ralph prd -m "Add a user dashboard with profile and settings"

# Or read task description from a file
ralph prd -f requirements.md

When using -m or -f flags, Claude Code will:

  1. Ask you clarifying questions about the feature
  2. Generate a comprehensive PRD based on your answers
  3. Create both prd.json and progress.txt files

Feel free to modify the shape of the tasks, so long as the started and complete fields remain as booleans.

This default PRD task shape was inspired by this article from Anthropic

Using AI to iterate on this PRD file itself is a great way to bootstrap Ralph's work!

Start the Ralph Wiggum loop:

Flags

-i, --max-iterations <number>    Maximum number of iterations to run (default: 10)
-s, --sequential                 Process tasks in sequential order instead of by priority
-v, --version                    Print version number
-h, --help                       Print help information

Subcommands

prd <options>       Generate a prd.json file
  --sample          Generate sample prd.json file
  -m, --message <text>    Task description for interactive PRD generation
  -f, --file <path>       File containing task description

Development

You must have Bun installed globally.

To install dependencies:

To run:

To link the global ralph command to this local development version: