Ralph Loop - Explained

Presentation One Pager

What Problem Does Ralph Loop Solve?

Context rot occurs when an AI coding tools have gather so much context that it loses track of the overall task due to the complexity or length of the prompt/ conversation. This can lead to incomplete or incorrect outputs. The Ralph Loop addresses this by breaking down tasks into smaller, manageable user stories and iteratively processing them. Each iteration creates a new instance with a fresh context which focuses on completing one user story at a time, allowing the AI to maintain context and deliver accurate results. This method stores important state information for next instance to pick up from where it left off within a progress file so that each iteration builds upon the last with only the necessary context.

What is a Ralph Loop?

A Ralph Loop is a method of using an AI CLI tool (like Claude or GPT-4) to iteratively process tasks defined in a prompt file. The loop continues until the AI indicates that all tasks are complete or a maximum number of iterations is reached.

The Ralph loop alone is neat basic programming concept, but it can be combined with other skills and scripts to create powerful automation workflows.

Simple

#!/bin/bash
for i in {1..10}; do
  claude -p prompt.md
done

Real

bash
MAX_ITERATIONS=10
AI_TOOL_CMD="claude --dangerously-skip-permissions"

for i in $(seq 1 $MAX_ITERATIONS); do
  # Call AI CLI tool with prompt file and capture output and errors.
  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | $AI_TOOL_CMD 2>&1 | tee /dev/stderr) || true
  
  # Is all tasks complete?
  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
    echo ""
    echo "Ralph completed all tasks!"
    exit 0
  fi
  
  echo "Iteration $i complete. Continuing..."
  sleep 2
done

Is Ralph Loop the only workflow/Process to solve this problem?

Nope there are many other tools like Get Shit Done. Make makes workflows like this one powerful is the steps and prompts that help AI tools find the right information for the task at hand.

User Workflow

1. Define PRD: Using the PRD skill, create a detailed Product Requirements Document (PRD) that outlines the features and specifications of the desired application.

2. Generate User Stories: Utilize ralph skill to convert the PRD to json prd output to break down the PRD into manageable user stories that capture the functionality from an end-user perspective.

3. Run the Loop: Execute the Ralph Loop script, which will process the user stories iteratively. The AI will generate code snippets, configurations, and other necessary components based on the user stories.

4. Review and Refine: After each iteration, review the output generated by the AI. Make any necessary adjustments to the prompt file or user stories to ensure the generated code meets the desired specifications. Then you can start start the process again, continue till you are out of features.

Automated Setup Steps - Claude Default

1. Clone the Repository: Start by cloning the Ralph Loop repository to your local machine.
2. Copy scripts/ralph Folder: Copy the scripts/ralph folder from the cloned repository to your project directory where you want to run the Ralph Loop.
3. Install AI Skills: Ensure you have the PRD and ralph skills installed and accessible in your environment. Check your AI cli tool documentation for skill installation instructions. However most of the time this would be in your project folder under .github/skills or .claude/skills

./scripts/ralph/install.sh

Manual Setup Steps

1. Install AI CLI Tool: Ensure you have an AI CLI tool like Claude or GPT-4 installed and configured on your system.
2. Install AI Skills: Make sure you have the PRD and ralph skills installed and accessible in your environment. Check your AI cli tool documentation for skill installation instructions. However most of the time this would be in your project folder under .github/skills or .claude/skills
3. Configure Script: Update the AI_TOOL_CMD variable in the Ralph Loop script to match your AI CLI tool command. For example, if using Claude, it might be claude --dangerously-skip-permissions.
4. Copy Ralph Files: Copy the Ralph Loop script and prompt file into your project directory where you want to run the loop.
5. Set Permissions: Ensure the Ralph Loop script has execute permissions. You can set this using the command:

   chmod +x path/to/ralph.sh

6. Done.

Usage

1. Create a PRD using the PRD skill.

claude 

/prd-local Create a PRD for an application for mac os that can monitor the mic audio and feed it back into my headset. This should be able to toggle on and off and set how much feedback like a volume slider. Use python for the tech.

Claude Will ask you some questions to clarify the requirements. Example:

1. What is the primary use case for this mic monitoring?
  - A. Hearing yourself while recording (podcasting, streaming, music)
  - B. Communication feedback during calls/meetings
  - C. Accessibility/hearing aid use case
  - D. General monitoring for any purpose

  2. What type of interface do you want?
  - A. Menu bar app only (minimal, lives in the top bar)
  - B. Small floating window with controls
  - C. Full application window
  - D. System tray with popup controls

  3. Should it remember settings between sessions?
  - A. Yes, persist last used input/output devices and volume
  - B. Yes, but only volume level
  - C. No, always start fresh with defaults
  - D. Let user choose in preferences

  4. Audio device selection:
  - A. Let user pick specific input mic and output headset from lists
  - B. Just use system default input and output
  - C. Let user pick input only, always use default output
  - D. Both options (default with ability to override)

  5. Any additional features needed?
  - A. Just toggle and volume - keep it simple
  - B. Add latency adjustment control
  - C. Add keyboard shortcut for toggle
  - D. Multiple of the above (please specify which)

  Please respond with your choices (e.g., "1A, 2A, 3A, 4D, 5C").

2. Convert the PRD to json user stories using the ralph skill.

/ralph-local convert @tasks/prd-mic-monitor.md to prd.json

3. Run the Ralph Loop script to start processing the user stories and generating code.

./scripts/ralph/ralph.sh
---

═══════════════════════════════════════════════════════
  Ralph Iteration 1 of 10
═══════════════════════════════════════════════════════
US-001 is complete. There are still 9 more stories with `passes: false` (US-002 through US-010), so I'm done with this iteration.

**Summary of US-001 completion:**
- Initialized git repo on branch `ralph/mic-monitor`
- Created `requirements.txt` with rumps, sounddevice, numpy
- Created `mic_monitor.py` as main entry point
- Created empty `audio_engine.py` and `settings.py` modules
- Typecheck passes with mypy
- Committed all changes and updated PRD to mark US-001 as complete
- Created progress.txt with codebase patterns and initial progress log
Iteration 1 complete. Continuing...

═══════════════════════════════════════════════════════
  Ralph Iteration 2 of 10
═══════════════════════════════════════════════════════
US-002 is complete. The remaining untracked files (scripts/ and tasks/) are not part of this story.

Looking at the PRD, there are still 8 more user stories with `passes: false` (US-003 through US-010), so another iteration will pick up the next story.

**Summary of US-002 completion:**
- Implemented `SettingsManager` class in `settings.py` with:
  - Settings stored at `~/Library/Application Support/MicMonitor/config.json`
  - Default values: volume=50, latency_ms=20, monitoring_enabled=False
  - `load()` method that reads config or returns defaults
  - `save()` method that writes settings to config file
  - Property accessors with validation
- Typecheck passes
- Committed with message: `feat: [US-002] - Settings manager module`
- Updated PRD and progress.txt
Iteration 2 complete. Continuing...

═══════════════════════════════════════════════════════
  Ralph Iteration 3 of 10
═══════════════════════════════════════════════════════
US-003 is complete. Looking at the PRD, there are still 7 more stories with `passes: false` (US-004 through US-010), so I'll end my response here for the next iteration to pick up US-004.

**Summary of US-003 completion:**
- Implemented `AudioEngine` class with:
  - `start()` - begins audio passthrough using sounddevice.Stream with callback
  - `stop()` - stops and closes stream cleanly
  - `set_volume(0-100)` - adjusts gain in real-time
  - Uses system default input/output devices
- Typecheck passes
- Committed: `feat: [US-003] - Audio engine with passthrough`
- Updated PRD (`passes: true`) and progress.txt
Iteration 3 complete. Continuing...

4. Review the generated code and make any necessary adjustments. You can rerun the Ralph Loop script as needed to continue processing remaining user stories until all tasks are complete.