rslph

Ralph Wiggum Loop - Autonomous AI Coding Agent

rslph is a Rust CLI application that implements the Ralph Wiggum Loop pattern: an autonomous AI coding agent that breaks down complex tasks into iterative steps and executes them using Claude AI. Each iteration starts with fresh context to prevent context pollution while preserving accumulated learnings through a persistent progress file. Features a rich TUI for real-time monitoring of execution.

Features

Fresh Context Per Iteration - Each iteration resets Claude's context, preventing context window exhaustion while maintaining progress through the persistent progress file
Progress File as Memory - Accumulated learnings survive across iterations, allowing Claude to learn from past attempts and avoid repeating failures
Rich TUI Interface - Real-time monitoring with live Claude output, collapsible message threads, keyboard navigation, and Claude Code-style visual design
VCS Auto-Commit - Automatic Git or Sapling commits after each iteration, creating a clear audit trail
Flexible Configuration - Configure via TOML config file, environment variables, or CLI flags with clear precedence rules
Built-in Evaluation Framework - Benchmark agent performance with hidden test suites and multi-trial statistics
Multiple Prompt Modes - Choose between basic rslph prompts, GSD-adapted prompts, or strict test-driven development flow
Token Tracking - Monitor Claude API token usage (input, output, cache creation, cache reads) across iterations

Prerequisites

Before installing rslph, ensure you have:

Rust toolchain - Install from rustup.rs

Claude CLI - Install and authenticate the Claude CLI tool

# Install Claude CLI (instructions at https://github.com/anthropics/anthropic-cli)
# Authenticate
claude auth

Git or Sapling VCS - For auto-commit functionality

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/rslph.git
cd rslph

# Build release binary
cargo build --release

# Binary will be at: target/release/rslph

# Optional: Add to PATH or create symlink
sudo ln -s $(pwd)/target/release/rslph /usr/local/bin/rslph

Quick Start

Create a plan from an idea:
```
rslph plan "create a hello world program in Python"
```
This generates a structured progress.md file with tasks.
Execute the plan autonomously:
```
rslph build progress.md
```
Watch in the TUI as Claude iterates through tasks, commits changes, and completes the plan.

What happens:

Claude reads the plan and current codebase
Executes the next task, updates code
Commits changes to Git/Sapling
Updates progress.md with results
Repeats until RALPH_DONE marker appears or max iterations reached
Each iteration has fresh context but sees accumulated progress

Commands Reference

`rslph plan`

Transform an idea into a structured progress file that the build command can execute.

rslph plan <PLAN> [OPTIONS]

Arguments:

<PLAN> - Path to plan file or inline text describing your goal

Options:

--adaptive - Enable adaptive mode with clarifying questions for detailed plans
--mode <MODE> - Prompt mode: basic, gsd, or gsd_tdd (default: basic)
--no-tui - Disable TUI and use plain output
--config <CONFIG> - Override config file path
--claude-path <PATH> - Override Claude CLI path
--max-iterations <N> - Override max iterations setting

Examples:

# Inline plan
rslph plan "add user authentication to my web app"

# From file
rslph plan idea.txt

# With adaptive mode for complex plans
rslph plan --adaptive complex-feature.txt

# Using GSD test-driven mode
rslph plan --mode gsd_tdd "implement a calculator library"

`rslph build`

Execute tasks from a progress file iteratively with fresh context.

rslph build <PLAN> [OPTIONS]

Arguments:

<PLAN> - Path to progress file (typically progress.md)

Options:

--once - Run only a single iteration (for debugging)
--dry-run - Preview what would happen without executing
--max-iterations <N> - Override max iterations (default: 20)
--mode <MODE> - Prompt mode: basic, gsd, or gsd_tdd
--no-tui - Disable TUI interface
--config <CONFIG> - Override config file path
--claude-path <PATH> - Override Claude CLI path

Examples:

# Normal execution with TUI
rslph build progress.md

# Single iteration for testing
rslph build --once progress.md

# Preview without execution
rslph build --dry-run progress.md

# With custom iteration limit
rslph build --max-iterations 50 progress.md

TUI Controls:

q - Quit
j/k - Scroll down/up
PageUp/PageDown - Page navigation
t - Toggle thinking blocks collapsed/expanded
c - Toggle conversation view (split screen with all messages)

`rslph eval`

Run evaluation benchmarks in isolated environments with hidden test suites.

rslph eval [PROJECT] [OPTIONS]

Arguments:

[PROJECT] - Project to evaluate (built-in or directory path)

Options:

--list - List available built-in projects
--trials <N> - Number of independent trials to run (default: 1)
--modes <MODES> - Comma-separated modes to compare: basic,gsd,gsd_tdd
--keep - Keep temporary workspace after completion (for debugging)
--max-iterations <N> - Override max iterations
--no-tui - Disable TUI dashboard
--config <CONFIG> - Override config file path

Built-in Projects:

calculator - Simple calculator with arithmetic operations
fizzbuzz - FizzBuzz implementation with test cases

Examples:

# List available projects
rslph eval --list

# Single evaluation
rslph eval calculator

# Multiple trials for statistics
rslph eval --trials 5 fizzbuzz

# Compare prompt modes
rslph eval --modes basic,gsd,gsd_tdd calculator

# Evaluate custom project with tests
rslph eval ./my-project --trials 3

Output:

Results saved to JSON: ~/.rslph/evals/eval-results-{project}-{date}.json
Statistics: pass rate, avg tokens, iteration count with min/max/mean/variance
Multi-mode comparison tables when using --modes

Configuration

Config File Location

rslph uses XDG-compliant configuration:

~/.config/rslph/config.toml

Create this file to customize default behavior.

Example Configuration

# Path to Claude CLI executable (resolved via 'which' if relative)
claude_path = "claude"

# Maximum iterations before stopping (default: 20)
max_iterations = 20

# Enable TUI mode by default (default: true)
tui_enabled = true

# Number of recent messages to display in TUI (default: 10)
tui_recent_messages = 10

# Timeout in seconds for each iteration (default: 600)
iteration_timeout = 600

# Maximum retries for timed-out iterations (default: 3)
timeout_retries = 3

# Default prompt mode (basic, gsd, gsd_tdd)
prompt_mode = "basic"

# Directory for eval workspaces and results (default: ~/.rslph/evals)
eval_dir = "~/.rslph/evals"

# Notification interval - every N iterations (default: 10)
notify_interval = 10

# Number of recent threads to display (default: 5)
recent_threads = 5

# Shell for notify script execution (default: /bin/sh)
notify_shell = "/bin/sh"

# Optional: Override plan/build prompt files
# plan_prompt = "/path/to/custom_plan_prompt.md"
# build_prompt = "/path/to/custom_build_prompt.md"

Environment Variables

Override config with environment variables using the RSLPH_ prefix:

export RSLPH_MAX_ITERATIONS=50
export RSLPH_TUI_ENABLED=false
export RSLPH_PROMPT_MODE=gsd_tdd
export RSLPH_CLAUDE_PATH=/custom/path/to/claude

Configuration Precedence

Settings are applied in this order (later overrides earlier):

Default values (hardcoded in the application)
Config file (~/.config/rslph/config.toml)
Environment variables (RSLPH_*)
CLI flags (highest precedence)

Prompt Modes

rslph supports three prompt engineering approaches:

`basic` (Default)

The original rslph prompts focused on iterative task execution with progress file updates.

Best for: General-purpose autonomous coding tasks
Backward compatible with existing workflows
Use when: You want tried-and-tested prompts

`gsd` (Get Shit Done)

GSD-adapted prompts with structured XML format and "must-haves" specification.

Best for: Complex multi-phase projects with clear requirements
Features: Explicit success criteria, structured output, must-haves tracking
Use when: You have well-defined requirements and want structured execution

`gsd_tdd` (Test-Driven Development)

Strict test-driven development flow with three-phase cycle (write test → implement → refactor).

Best for: Projects requiring high code quality and test coverage
Features: Enforced red-green-refactor cycle, automatic test infrastructure setup
Use when: Building libraries, APIs, or critical functionality requiring tests

Select mode:

# Via CLI flag
rslph plan --mode gsd_tdd "build a calculator library"

# Via config file
# config.toml: prompt_mode = "gsd_tdd"

# Via environment
export RSLPH_PROMPT_MODE=gsd

How It Works

The Ralph Wiggum Loop is named after The Simpsons character who persists despite setbacks. It emphasizes iterative self-correction over single-pass perfection.

The Loop Pattern

Plan Phase:
- Claude transforms your idea into a structured progress file
- Tasks are broken down into concrete, executable steps
- Success criteria and verification steps are defined
Build Phase (iteration loop):
- Read: Claude reads the progress file + current codebase
- Execute: Completes the next task, modifying code as needed
- Commit: Changes are committed to VCS with descriptive message
- Update: Progress file is updated with results and learnings
- Check: If RALPH_DONE marker appears, loop exits successfully
- Repeat: Fresh context for next iteration (no context pollution)

Key Insight: Progress File as Memory

The progress file is the sole memory mechanism between iterations:

Each iteration Claude starts with fresh context (no accumulated tokens)
Progress file contains accumulated learnings (what was tried, what worked, what failed)
Claude reads this file every iteration, learning from past attempts
Best of both worlds: fresh context + persistent memory

VCS Integration

After each successful iteration, rslph automatically commits:

git commit -m "Iteration 3: Implemented user authentication handler"

This creates an audit trail and allows easy rollback if needed.

Project Structure

After running rslph, your project might look like:

my-project/
├── progress.md          # Generated by 'plan', updated by 'build'
├── src/                # Your code (created/modified by Claude)
│   ├── main.py
│   └── auth.py
└── .git/               # VCS commits after each iteration

Advanced Usage

Custom Prompt Files

Override default prompts by setting paths in config:

plan_prompt = "~/.config/rslph/my_plan_prompt.md"
build_prompt = "~/.config/rslph/my_build_prompt.md"

This allows power users to customize Claude's instructions.

Evaluation Workflow

Benchmark your prompt engineering:

# Compare all modes across 5 trials
rslph eval --modes basic,gsd,gsd_tdd --trials 5 calculator

# Analyze results JSON
cat ~/.rslph/evals/eval-results-calculator-multimode-*.json | jq

Results include:

Pass rate (tests passed / total tests)
Token usage statistics (mean, variance, min, max)
Iteration count statistics
Per-trial detailed logs

Debugging Failed Builds

# Run single iteration to see exact failure
rslph build --once progress.md

# Keep workspace for inspection
rslph eval --keep my-project

# Disable TUI for clean logs
rslph build --no-tui progress.md 2>&1 | tee build.log

Troubleshooting

Claude CLI hangs

If the Claude CLI hangs, this is a known issue. Current workaround:

rslph uses --internet flag internally to prevent hanging
Ensure your Claude CLI is up to date
Check authentication: claude auth

Timeout errors

If iterations timeout (default 600s):

# Increase timeout in config.toml
iteration_timeout = 1200  # 20 minutes
timeout_retries = 5

VCS not auto-committing

Ensure Git or Sapling is initialized:

git init
# or
sl init

rslph auto-detects VCS and commits after each iteration.

License

[License information - add your chosen license here]

Contributing

Contributions welcome! This project uses:

Language: Rust (edition 2021)
TUI: ratatui
Config: figment (TOML)
CLI: clap
Testing: E2E tests with fake Claude simulation

Acknowledgments

Pattern origin: Geoffrey Huntley's Ralph Wiggum Loop concept (late 2025)
Reference implementation: portableralph
Claude AI: Anthropic's Claude powers the autonomous execution

Built with Rust. Powered by Claude. Inspired by Ralph Wiggum's persistence.

rslph 0.1.0

rslph

Features

Prerequisites

Installation

From Source

Quick Start

Commands Reference

rslph plan

rslph build

rslph eval

Configuration

Config File Location

Example Configuration

Environment Variables

Configuration Precedence

Prompt Modes

basic (Default)

gsd (Get Shit Done)

gsd_tdd (Test-Driven Development)

How It Works

The Loop Pattern

Key Insight: Progress File as Memory

VCS Integration

Project Structure

Advanced Usage

Custom Prompt Files

Evaluation Workflow

Debugging Failed Builds

Troubleshooting

Claude CLI hangs

Timeout errors

VCS not auto-committing

License

Contributing

Acknowledgments

`rslph plan`

`rslph build`

`rslph eval`

`basic` (Default)

`gsd` (Get Shit Done)

`gsd_tdd` (Test-Driven Development)