PageAI-Pro/ralph-loop

What it solves

Ralph Loop is designed to automate long-running software development tasks. It prevents AI agents from losing focus or stopping prematurely by iteratively working through a structured task list until a project is complete, effectively allowing an AI to code for days at a time.

How it works

Ralph operates as a loop that manages an agentic AI CLI (such as Claude Code, Cursor, or Gemini) within isolated Docker Sandboxes. In each iteration, the system follows a specific workflow:

1. Task Selection: It identifies the highest-priority incomplete task from a lookup table.
2. Execution: The agent works through the detailed steps of that task.
3. Verification: The agent runs tests, linting, and type checking to verify the work.
4. Completion: Once verified, the agent takes a screenshot, updates the task status, and commits the changes.

Users can steer the agent by editing a STEERING.md file to inject critical priorities that the agent must address before continuing with the standard task list.

Who it’s for

Software developers who want to automate the implementation of a full Product Requirements Document (PRD) and use agentic AI to handle the repetitive cycle of coding, testing, and committing changes autonomously.

Highlights

• PRD-to-Task Automation: Includes a prd-creator skill to turn unstructured requirements into a formal PRD and a detailed task list.
• Sandboxed Execution: Uses Docker Sandboxes for secure, isolated environments with deterministic naming for different agents.
• Observability: Provides live stream previews, iteration timing, and historical logs for every step the agent takes.
• Extensible Skills: Features a library of reusable "skills" (specialized knowledge and workflows) for various frameworks like React, PostgreSQL, and Playwright.
• Human-in-the-loop: Uses semantic promise tags (e.g., <promise>BLOCKED</promise>) to signal when human intervention or decisions are required.