Simple Ralph 🚀

"I'm helping!" - Ralph Wiggum

A minimal, focused orchestration framework for AI coding agents inspired by the Ralph Wiggum Technique. Simple Ralph uses a straightforward for-loop to incrementally complete a backlog of tasks, one at a time.

Quick Summary

Simple Ralph implements the Ralph Wiggum Technique: a simple orchestration pattern that:

• Single Task Focus: Works on ONE task at a time, never multitasks
• Agentic Selection: The AI agent analyzes context and decides which task to work on
• Tight Feedback Loops: Verifies after every change (tests, type checks, linting)
• Keeps CI Green: Never commits breaking changes
• Simple State: JSON file for tasks (prd.json), text file for memory (progress.txt)

Installation

Quick Install

# Clone the repository
git clone <repository-url>
cd simple-ralph

# Run the installer
./install_ralph.sh

This installs Simple Ralph to ~/.ralph/ and creates the simple-ralph command.

The installer automatically adds ~/.ralph/bin to your PATH by updating your shell config (~/.zshrc, ~/.bashrc, or ~/.bash_profile). Restart your terminal or run source ~/.zshrc (or equivalent) to apply.

Usage

1. Initialize Your Project

Navigate to your project root and run:

cd your-project
simple-ralph --setup

This will:

1. Create the plans directory
2. Auto-generate prd.json by analyzing your codebase using AI

Important: You must authenticate Docker sandbox first before running this command (see Docker Sandbox Authentication).

Using Gemini Instead of Claude

To use Gemini for PRD generation:

simple-ralph --setup --agent gemini

Using Codex (OpenAI)

To use Codex for PRD generation:

simple-ralph --setup --agent codex

Note: Codex runs directly from your host machine (not Docker sandbox). Ensure OPENAI_API_KEY is set and the Codex CLI is installed.

Skip PRD Generation

To create just the empty templates without AI-generated tasks:

simple-ralph --setup --no-generate

Files Created

• plans/prd.json - Your task backlog (auto-generated or empty template)
• plans/progress.txt - AI agent's memory log
• plans/RALPH_EXPLANATION.md - Explanation of the Ralph technique
• plans/GENERATE_PRD_PROMPT.md - Prompt template for PRD generation

2. Define Your Tasks

Edit plans/prd.json to define your backlog:

[
  {
    "id": "task-1",
    "description": "Set up project structure with configuration",
    "passes": false,
    "context": "Initialize the basic project scaffolding."
  },
  {
    "id": "task-2",
    "description": "Implement user authentication",
    "passes": false,
    "context": "Use JWT tokens for auth. Depends on task-1."
  }
]

• id: Unique identifier
• description: Clear, actionable task description
• passes: false = incomplete, true = complete
• context: Additional details for the AI agent

3. Run Ralph

simple-ralph [max_iterations]

Example:

simple-ralph 10

Selecting an AI Agent

By default, Ralph uses Claude. To use Gemini instead:

simple-ralph --agent gemini 10

Valid agents: claude, gemini, codex

Note: Claude and Gemini run in Docker sandbox. Codex runs directly from the host machine.

The script will:

1. Send the full backlog + recent history to the AI agent
2. Agent selects highest priority task and implements it
3. Runs verification checks
4. Marks task complete and commits changes
5. Repeats until all tasks are done or max iterations reached

Custom Verification with ralph-post-hook.sh

Create a custom verification script in your project root:

#!/usr/bin/env bash
# ralph-post-hook.sh

set -euo pipefail

echo "Running custom verification..."

# Add your project-specific checks here:
npm test
npm run lint
npm run typecheck

# Python example:
# pytest
# mypy .
# flake8

# Rust example:
# cargo test
# cargo clippy

echo "All checks passed!"

Make it executable:

chmod +x ralph-post-hook.sh

If this file exists and is executable, Ralph will use it instead of auto-detected checks.

Docker Sandbox Authentication

Simple Ralph uses Docker Desktop's sandbox feature to run AI coding agents in isolation. For more details, see the Docker AI Sandboxes documentation.

First-Time Setup

Before running ralph.sh, you must authenticate your workspace for the AI agent you want to use:

Claude

# Start an interactive sandbox session
docker sandbox run claude

# Inside the sandbox, authenticate:
/login

# Follow the prompts to complete authentication
# Then exit the sandbox
exit

Gemini

# Start an interactive sandbox session
docker sandbox run gemini

# Inside the sandbox, authenticate:
/login

# Follow the prompts to complete authentication
# Then exit the sandbox
exit

Note: Authentication persists across sandbox sessions for the same workspace.

Common Issues

Issue	Solution
Docker sandbox command not available	Enable AI Sandboxes in Docker Desktop settings
Invalid API key	Run /login in an interactive sandbox session for your selected agent
Sandbox times out	Increase timeout in ralph.sh (default: 600s)
Wrong agent selected	Use RALPH_AI_AGENT=gemini or RALPH_AI_AGENT=claude or RALPH_AI_AGENT=codex

Codex Setup

Codex runs directly from your host machine (not in Docker sandbox). To set it up:

1. Install Codex CLI: Follow instructions at https://github.com/openai/codex
2. Set API Key:

   export OPENAI_API_KEY="your-api-key"

3. Run with Codex:

   RALPH_AI_AGENT=codex ./plans/ralph.sh 10

Project Structure

your-project/
├── plans/
│   ├── ralph.sh              # Orchestration script
│   ├── prd.json              # Task backlog
│   ├── progress.txt          # AI memory/log
│   ├── RALPH_EXPLANATION.md  # Technique explanation
│   └── GENERATE_PRD_PROMPT.md # PRD generation prompt
├── ralph-post-hook.sh        # (Optional) Custom verification
└── ... your code ...

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Ralph Main Loop                          │
├─────────────────────────────────────────────────────────────┤
│  for iteration in 1..max_iterations:                        │
│    1. Gather incomplete tasks from prd.json                 │
│    2. Read last 250 lines of progress.txt                   │
│    3. Send backlog + history to AI agent                    │
│    4. Agent selects highest priority task                   │
│    5. Agent implements the task                             │
│    6. Agent reports: COMPLETED_TASK_ID: task-X              │
│    7. Run verification (ralph-post-hook.sh or auto-detect)  │
│    8. Mark task complete in prd.json                        │
│    9. Append to progress.txt                                │
│   10. Git commit                                            │
│   11. If all tasks done → "promise complete here" → exit    │
└─────────────────────────────────────────────────────────────┘

Best Practices

Task Sizing

• Keep tasks small (completable in one iteration)
• Break large features into multiple tasks
• Each task should be independently verifiable

Task Ordering

• The AI agent determines task order at runtime
• It analyzes dependencies, context, and project state
• Use the context field to hint at dependencies between tasks

Context Field

• Include relevant file paths
• Mention dependencies on other tasks
• Provide examples or specifications

Troubleshooting

Script fails with "jq: command not found"

# macOS
brew install jq

# Linux
apt-get install jq

Script fails with "expect: command not found"

# macOS
brew install expect

# Linux
apt-get install expect

Agent did not report a COMPLETED_TASK_ID

Check /tmp/ralph_claude_output.log for the full agent output. The agent must include this exact line in its output:

COMPLETED_TASK_ID: task-X

Verification failing

• Run your verification commands manually to debug
• Check that ralph-post-hook.sh is executable
• Ralph enforces CI green - fix issues before continuing

License

MIT