Ralphy

A terminal UI for managing Ralph Loop iterations - an AI-powered development workflow that iterates through user stories until completion.

Features

• Two-panel layout - Stories list on the left, live output on the right
• Real-time progress tracking - Progress bar, ETA, and per-story timing
• File watching - Automatically reloads when prd.json changes
• Interactive controls - Vim-style navigation, search, panel switching
• Process management - Start/stop iterations, view live output

Requirements

• Go 1.22+
• opencode CLI in your PATH
• A project with scripts/ralph/ containing:
  • prd.json - Product Requirements Document with user stories
  • prompt.md - AI agent prompt

Installation

Quick Install (from source)

git clone https://github.com/thenomadcode/ralphy.git
cd ralphy
./install.sh

Manual Install

git clone https://github.com/thenomadcode/ralphy.git
cd ralphy
go build -o ralphy .
sudo cp ralphy /usr/local/bin/

Pre-built Binary

Download from Releases and add to your PATH.

Usage

# Run from any project with scripts/ralph/ folder
cd ~/my-project
ralphy

# Custom ralph directory
ralphy --ralph-dir ./custom/path

# Explicit file paths
ralphy --prd ./prd.json --prompt ./prompt.md

Keyboard Shortcuts

Key	Action
r	Start/restart iteration
Tab	Switch between panels
↑/k	Scroll up
↓/j	Scroll down
g	Jump to top
G	Jump to bottom
/	Search stories
?	Toggle help
q	Quit

PRD Format

Your prd.json should follow this structure:

{
  "project": "My Project",
  "branchName": "feature/awesome",
  "description": "Project description",
  "userStories": [
    {
      "id": "S1",
      "title": "Story title",
      "description": "What needs to be done",
      "priority": 1,
      "passes": false,
      "notes": "",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"]
    }
  ]
}

How It Works

1. Ralphy reads your prd.json to get the list of user stories
2. When you press r, it runs opencode run <prompt.md content>
3. The AI works through stories, updating prd.json as they pass
4. Ralphy detects file changes and updates the UI in real-time
5. Iterations continue until all stories pass or max iterations reached

License

MIT License - see LICENSE for details.