This repository provides a comprehensive guide and tooling for autonomous AI coding loops using Geoff Huntley's Ralph methodology. It targets developers and researchers seeking to leverage LLMs for complex software development, offering a structured framework for iterative code generation, planning, and execution to enhance AI agent autonomy and consistency.

How It Works

Ralph operates via a three-phase process: defining requirements, planning, and building. A bash script (loop.sh) orchestrates LLM iterations using specific prompts (PROMPT_plan.md, PROMPT_build.md). The LLM acts on instructions, generates/updates an IMPLEMENTATION_PLAN.md, and interacts with code. Key principles include maximizing context, employing backpressure (tests, validation), and autonomous operation ("Let Ralph Ralph") within secure, sandboxed environments.

Quick Start & Requirements

• Primary Install: Make loop.sh executable (chmod +x loop.sh) and run it.
• Prerequisites: LLM CLI (e.g., Claude CLI), specific LLM models (Opus for complex reasoning, Sonnet for speed), sandboxing environment (e.g., Docker) due to --dangerously-skip-permissions.
• Setup: Requires LLM CLI configuration and awareness of security implications for automated tool execution.

Highlighted Details

• Dual-Mode Operation: Supports PLANNING (gap analysis, plan generation) and BUILDING (implementation, commits) modes.
• Context Efficiency: Maximizes LLM context by processing single tasks per loop iteration.
• Robust Backpressure: Integrates tests, type checks, and builds. Enhancements include Acceptance-Driven Backpressure (tests derived from criteria) and LLM-as-Judge for subjective quality.
• Work Branch Scoping: plan-work mode creates scoped plans for feature branches, improving determinism.
• SLC Release Strategy: Aligns AI tasks with product value by mapping JTBDs to user activities and Simple, Lovable, Complete (SLC) releases.
• Security: --dangerously-skip-permissions mandates sandboxing (e.g., Docker) for autonomous tool execution risks.

Maintenance & Community

Associated with Geoff Huntley and Clayton Farr. Documentation focuses on technical implementation; no explicit community channels or maintenance schedules are provided.

Licensing & Compatibility

No specific open-source license is mentioned in the provided README content, requiring further investigation for commercial use.

Limitations & Caveats

The --dangerously-skip-permissions flag necessitates strict sandboxing. The system relies on LLM nondeterminism, requiring iterative tuning and a "plan is disposable" approach. The absence of explicit licensing is a significant adoption caveat.