A Ralph Wiggum Loop implementation that works™

Ralph is a long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion. This allows for long running agent loops, effectively enabling AI to code for days at a time.

This is an implementation that actually works, containing a hackable script so you can configure it to your env and favorite agentic AI CLI. It's set up by default to use Claude Code in a Docker sandbox, but supports many other agentic AI CLIs.

👉 Watch the video for an in-depth walkthrough.

• Getting Started
  • (Optional) Set up code base
  • 1️⃣ Step 1: Install Ralph
  • 2️⃣ Step 2: Create a PRD + task list
  • 3️⃣ Step 3: Set up the agent inside Docker sandbox
  • 4️⃣ Step 4: Run Ralph
• Running the Ralph Loop with custom options
  • (Optional) Adjusting to your language/framework
• How It Works
• How Is This Different from Other Ralphs?
• Steering the Agent
• Support
  • Promise Tags
  • Exit Codes
• Structure
• Skills
  • Available Skills
  • Skills Directory Structure
• Reference
  • Playwright configuration
  • Vitest configuration
  • Running with a different agentic CLI
  • Starting from scratch
• License

Getting Started

(Optional) Set up code base

I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:

npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git

If you must start from a blank slate, which is not recommended, see Starting from scratch. You can also go for a more barebone start by running npx create-vite@latest src --template react-ts

1️⃣ Step 1: Install Ralph

Run this in your project's directory to install Ralph.

npx @pageai/ralph-loop

2️⃣ Step 2: Create a PRD + task list

Use the prd-creator skill to generate a PRD from your requirements.<br/> Ope...