Skip to content
Search

Ralph-loop

lastmod 2026-03-12created 2026-03-121 edits

A long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion.

Automating development work with a long-running AI agent loop

About

  • A long-running AI loop system that repeatedly goes through a task list and works until completion
  • Runs AI CLIs such as Claude Code/Codex/Gemini safely in a Docker sandbox environment
  • How to run it
    • Step 1: Install Ralph npx @pageai/ralph-loop
    • Step 2: Write the PRD (product requirements document) and task list: generate a PRD from the requirements with the prd-creator skill and review each task
    • Step 3: Set up the agent inside the Docker sandbox
      • Log in with docker sandbox run claude .
      • Be sure to answer Yes to Bypass Permissions mode. This is why you use the sandbox
    • Step 4: Run Ralph ./ralph.sh -n 50 # run the Ralph Loop 50 times
  • How it works : in each iteration, Ralph does the following
    1. Finds the highest-priority incomplete task in the .agent/tasks.json file
    2. Proceeds through the task steps defined in .agent/tasks/TASK-{ID}.json in order
    3. Runs tests·lint·type checks
    4. Completes the task, takes a screenshot, updates the task status, and commits the changes
  • How this PageAI version differs from other Ralph Wiggum Loops
    • PRD generation and task list extraction from requirements
    • Task lookup table generated from the PRD
    • Breaks down task steps and splits them into manageable steps
    • Iteration progress tracking (shown with time)
    • Real-time output stream preview and activity phase detection (Thinking, Testing, etc.)
    • Captures screenshots of the current screen
    • Notifies you when human input is needed
    • History logging with clean output per iteration
    • Shows timing metrics for each iteration and the total time
    • Steering feature lets important tasks be handled first
    • Additionally
      • Enter unstructured requirements and the agent generates the PRD and task list automatically
      • Uses a task lookup table with individual detailed steps, so it scales well when hundreds of tasks need handling
      • Runs in a sandbox environment for stronger security
      • Shows progress and statistics so completed tasks are easy to check
      • Instructs the agent to write and run automated tests and screenshots for each task
      • Provides visibility and traceability into the agent's work, and
      • Shows the output stream and captures a full history log per iteration
  • MIT license

See also

Favorite site

author Zer0 sitemap