AI Ralph Technique - spinningideas/resources GitHub Wiki

AI Ralph Technique

Here is a summary of the Ralph loop, its mechanics, and how a developer can implement it generally.

The Ralph Loop Links

Repos

The Ralph Loop

Ralph is a technique and autonomous workflow designed to let AI agents build applications iteratively and autonomously. In its purest form, it is a simple shell loop (often a Bash script) that repeatedly pipes a prompt into an AI coding agent until a defined set of requirements is fully met.

Core Concept: Fresh Context and External Memory

The fundamental philosophy behind the Ralph loop is the elimination of "context rot." In traditional long-running AI sessions, the conversation history becomes bloated, leading to degraded performance and loss of instructions.

The Ralph loop solves this by spawning a fresh instance of the AI agent for every single iteration. Because the agent starts with a "clean slate" each time, it cannot rely on conversation history. Instead, memory is persisted externally through three specific mechanisms:

  1. Git History: The code commits made in previous iterations.
  2. Product Requirements Document (PRD): A file (often JSON or Markdown) tracking the status of tasks (e.g., pending vs. complete).
  3. Progress Log: A text file (e.g., progress.txt) where the agent appends learnings, context, and "where I left off" notes for the next instance.

How It Works

The loop operates linearly, executing one task at a time rather than attempting to build everything in parallel. The lifecycle of a single Ralph iteration typically follows this flow:

  1. Read Context: The fresh agent reads the prompt, the PRD, and the progress log to understand the project state.
  2. Select Task: The agent identifies the highest-priority item in the PRD that is not yet marked as complete.
  3. Implement: The agent writes the code to implement that specific story.
  4. Verify (Feedback Loop): The agent runs quality checks (type checks, linters, tests) to ensure the code works.
  5. Commit: If checks pass, the agent commits the changes to version control.
  6. Update State: The agent updates the PRD (marking the task "passed") and appends new learnings to the progress log.
  7. Repeat: The loop restarts, spawning a new agent to handle the next task.

How a Developer Can Use It

To utilize a Ralph loop generally, a developer needs to set up a specific environment and file structure. This approach relies on "context engineering"—ensuring the right cargo is loaded onto the train before it leaves the station.

1. Preparation Phase

Before running the loop, the developer must create the necessary artifacts:

  • The PRD: Create a detailed plan (often prd.md or prd.json) that breaks the project down into small, manageable user stories. Each item should be small enough to fit within a single context window (e.g., "Add a database column" rather than "Build the dashboard").
  • The Progress File: Create an empty file (e.g., progress.txt) for the agent to use as a scratchpad for future iterations.
  • The Prompt: Create a system prompt (e.g., prompt.md) containing instructions. This should tell the agent to read the PRD, pick a task, run tests, and update the tracking files.
  • The Script: Write a simple shell script (ralph.sh) to execute the loop. This script typically pipes the prompt into the agent CLI tool repeatedly.

2. Execution Phase

Run the shell script. The developer's role shifts from writing code to orchestrating the loop.

  • Monitoring: The developer may watch the progress.txt or Git log to see the agent's linear progress.
  • Automated Verification: It is critical to have a robust feedback loop. The script should ideally include commands for the agent to run tests or type-checkers. If the code breaks, the agent needs to see that failure output to correct itself within the iteration.
  • Browser Verification: For frontend tasks, developers can instruct the agent to use browser tools to verify UI changes.

3. Maintenance and Tuning

  • Updating Documentation: A best practice is to have the agent update a documentation file (like AGENTS.md) with discovered patterns or "gotchas" after each iteration. This allows future agents to "learn" the codebase conventions without reading every file.
  • Stop Condition: The loop should be configured to stop automatically when all items in the PRD are marked passes: true or COMPLETE.

4. Debugging

If the loop fails or produces poor results, the developer should check the progress.txt to see what the agent "thought" it did, or review the prd.json to see which task is stuck. Improving the detailed breakdown in the PRD is often the solution to improved performance.

See Also