Summary

Ralph-loop is a long-running AI agent framework designed to automate software development tasks through iterative loops, enabling AI to code continuously for days. It targets developers and researchers seeking to leverage AI for complex, extended coding projects, offering a hackable and observable system for AI-driven development.

How It Works

This project implements a "Ralph Wiggum Loop" concept, orchestrating AI agents within Docker Sandboxes for isolated execution. Each iteration involves identifying and executing tasks from a defined list, followed by automated testing, linting, and type checking. Changes are committed upon task completion. The system is designed to be hackable, supporting various AI CLIs and offering detailed observability through logs, screenshots, and timing metrics. A key feature is its ability to generate a Product Requirements Document (PRD) and task breakdown from initial user requirements.

Quick Start & Requirements

Installation is performed via npx @pageai/ralph-loop. Key prerequisites include Docker and Docker Sandboxes, along with a compatible AI agent CLI (e.g., Claude Code, Cursor). Development workflows assume Playwright, Vitest, TypeScript, ESLint, and Prettier. The initial sandbox setup for the first iteration takes approximately 5 minutes. Further documentation is available at ralphloop.sh.

Highlighted Details

• Automated PRD and task list generation from unstructured requirements.
• Detailed task breakdown into manageable steps.
• Sandboxed execution environment for enhanced security and isolation.
• Comprehensive observability: iteration progress, live stream preview, step detection, screenshot capture, and historical logging.
• Automated execution of tests, linting, and type checking per task.
• STEERING.md file allows prioritizing critical tasks during runtime.

Maintenance & Community

The provided README focuses on technical implementation and does not detail specific contributors, community channels (like Discord/Slack), or sponsorship information.

Licensing & Compatibility

The project is released under the MIT license, which permits commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

Users must configure the environment, including language/framework specifics and AI agent prompts, by editing files like .agent/PROMPT.md. Network access within Docker Sandboxes may require explicit policy configuration. Authentication persistence for AI CLIs within sandboxes can be challenging, often necessitating API key setup. The overall effectiveness is dependent on the capabilities of the selected AI agent.