gptme-ralph

A gptme plugin implementing the Ralph Loop pattern - iterative execution with context reset between steps.

Overview

The Ralph Loop pattern (named after Ralph Wiggum from a popular AI coding video) solves the problem of context rot/degradation in long-running agent tasks by:

Spec + Plan: Give the agent a specification and implementation plan
Iterative Execution: Work through the plan step by step
Context Reset: After each step, reset context to just spec + updated plan
File Persistence: Progress persists in files/git, NOT in LLM context

This keeps the agent's context fresh and focused, preventing the quality degradation that happens when context fills up with old information.

Installation

# Add to your gptme.toml
[plugins]
enabled = ["gptme_ralph"]
paths = ["path/to/gptme-contrib/plugins/gptme-ralph/src"]

Usage

Basic Loop

from gptme_ralph import run_loop, create_plan

# Create a plan file
create_plan("Build a REST API with user authentication", "api_plan.md")

# Edit the plan to add specific steps, then run
run_loop("spec.md", "api_plan.md")

Plan File Format

Plans use markdown with checkboxes:

# Implementation Plan

Task: Build REST API with authentication

## Steps

- [ ] Step 1: Set up FastAPI project structure
- [ ] Step 2: Implement user model and database
- [ ] Step 3: Add JWT authentication
- [x] Step 4: Create CRUD endpoints (completed)
- [ ] Step 5: Add tests

Background Execution

For long-running tasks:

# Start in background
run_loop("spec.md", "plan.md", background=True, max_iterations=30)
# Returns: "Background Ralph Loop started in session: ralph_loop_abc123"

# Check progress
check_loop("ralph_loop_abc123")

# Stop if needed
stop_loop("ralph_loop_abc123")

Backend Selection

Supports both Claude Code and gptme as the inner loop:

# Use Claude Code (default)
run_loop("spec.md", "plan.md", backend="claude")

# Use gptme
run_loop("spec.md", "plan.md", backend="gptme")

API Reference

`run_loop(spec_file, plan_file, **kwargs)`

Run a Ralph Loop with the given spec and plan.

Parameters:

spec_file: Path to the specification/PRD file
plan_file: Path to the implementation plan (markdown with checkboxes)
workspace: Working directory (default: current)
backend: "claude" or "gptme" (default: "gptme")
max_iterations: Maximum loop iterations (default: 50)
step_timeout: Timeout per step in seconds (default: 600)
background: Run in tmux session (default: False)

`create_plan(task_description, output_file, **kwargs)`

Create an initial implementation plan from a task description.

Parameters:

task_description: What to implement
output_file: Where to save the plan (default: "plan.md")
num_steps: Approximate number of steps (default: 5)
workspace: Working directory (default: current)

`check_loop(session_id)`

Check status of a background loop session.

`stop_loop(session_id)`

Stop a background loop session.

How It Works

Read Spec & Plan: Load the specification and current plan state
Find Current Step: Identify the first uncompleted step
Build Prompt: Create a focused prompt with spec + plan + current step
Execute: Run the backend (Claude/gptme) with the prompt
Check Completion: Re-read plan to see if step was marked complete
Loop or Exit: Continue to next step or exit if all done

The key insight is that each iteration gets a fresh context containing only:

The original specification
The current state of the plan
Instructions for the current step

This prevents the context from filling up with old tool outputs, failed attempts, and other noise.

When to Use

Good fit:

Multi-step implementation tasks
Long-running autonomous work
Tasks with clear step-by-step plans
Projects prone to context degradation

Not ideal for:

Quick one-off tasks
Highly interactive debugging
Tasks requiring continuous context

References

License

MIT