fete/.claude/rules/ralph-loops.md

Ralph Loop Guide

What is a Ralph Loop?

A Ralph Loop is an autonomous AI development pattern where a language model is invoked repeatedly in a loop, performing exactly one task per iteration. Each iteration is a fresh context — the model has no memory of previous runs. Persistence is achieved through files: the model reads project state from disk at the start of each iteration and writes its results back before stopping.

The name originates from Geoffrey Huntley's technique for autonomous coding with Claude Code. The core insight: by constraining each iteration to a single task and using files as shared memory, you get reliable, incremental progress without context window exhaustion.

Sources and further reading:

• Geoffrey Huntley — Everything is a Ralph Loop
• snarktank/ralph — Original implementation
• frankbria/ralph-claude-code — Claude Code adaptation

How Ralph Works in This Project

Directory Structure

Each Ralph run lives in its own directory under .ralph/:

.ralph/
└── my-run/
    ├── instructions.md    # Agent prompt (user-created, required)
    ├── meta.md            # Run metadata (auto-generated)
    ├── chief-wiggum.md    # Chief Wiggum directives (auto-generated template)
    ├── answers.md         # Human answers to questions (auto-generated template)
    ├── questions.md       # Questions raised by Ralph (auto-generated template)
    ├── progress.txt       # Iteration log (auto-generated template)
    └── run.log            # Execution log (auto-generated)

The Iteration Cycle

┌─────────────────────────────────┐
│  ralph.sh starts iteration N    │
│                                 │
│  1. Read project state          │
│     (files listed in            │
│      instructions.md)           │
│                                 │
│  2. Select ONE task             │
│     (by priority order)         │
│                                 │
│  3. Execute that task           │
│     (edit files as needed)      │
│                                 │
│  4. Append summary to           │
│     progress.txt                │
│                                 │
│  5. Stop                        │
│     (or emit COMPLETE signal)   │
└────────────┬────────────────────┘
             │
             ▼
     ralph.sh checks output
     for <promise>COMPLETE</promise>
             │
        ┌────┴────┐
        │ Found?  │
        ├─Yes─────┼──► Loop ends
        └─No──────┘
             │
             ▼
     Sleep 2s, start iteration N+1

File Roles

Each run directory contains files with specific roles:

File	Purpose	Who writes it
instructions.md	Defines what Ralph does, which files to read, task priorities	Human (before run)
progress.txt	Append-only iteration log — Ralph's memory across iterations	Ralph
chief-wiggum.md	Directives from the Chief Wiggum session	Chief Wiggum
answers.md	Human answers to Ralph's questions	Human
questions.md	Questions Ralph raises when encountering ambiguity	Ralph
meta.md	Run metadata (date, model, config)	Auto-generated
run.log	Execution log (start/stop times, iteration count)	ralph.sh

How to Run Ralph

Basic Usage

./ralph.sh .ralph/my-run

This runs the default configuration: up to 20 iterations, using Claude Opus, with Read/Edit/Write tools.

Prerequisites

The run directory must contain an instructions.md file. All other files are auto-created as templates if they don't exist.

Options

./ralph.sh <run-directory> [options]

Options:
  -n, --max-iterations N   Maximum iterations (default: 20)
  -m, --model MODEL        Claude model to use (default: opus)
  -t, --tools TOOLS        Allowed tools, quoted (default: "Read Edit Write")

Examples

# Short run with cheaper model
./ralph.sh .ralph/my-run -n 10 -m sonnet

# Run with more tools (e.g. for coding tasks)
./ralph.sh .ralph/my-run -n 30 -t "Read Edit Write Bash Glob Grep"

# New run
mkdir .ralph/my-new-task
# Write .ralph/my-new-task/instructions.md, then:
./ralph.sh .ralph/my-new-task -n 15

Path Convention in instructions.md

Use {{RUN_DIR}} as a placeholder for run-specific files. The script substitutes it automatically before passing the prompt to Claude:

{{RUN_DIR}}/progress.txt         # run-specific
{{RUN_DIR}}/chief-wiggum.md      # run-specific
{{RUN_DIR}}/answers.md           # run-specific
{{RUN_DIR}}/questions.md         # run-specific

All other file paths are relative to the project root as usual.

How to Communicate with Ralph

Ralph cannot be talked to directly. Communication happens through files:

As Chief Wiggum (directing Ralph)

Edit chief-wiggum.md in the run directory before starting the loop:

• ## Action Required — Ralph MUST address these, one per iteration, in order.
• ## Observations — Informational notes. Ralph may use them but is not required to act.

Ralph never modifies chief-wiggum.md. To confirm an item was addressed, check progress.txt.

As the Human (answering questions)

When Ralph raises a question in questions.md, write your answer in answers.md in the run directory. On the next iteration, Ralph will process the answer.

Monitoring Progress

• progress.txt — Append-only log of every iteration. What Ralph did and why.
• run.log — Execution metadata (start time, iterations, completion status).
• Project files — Diff the files Ralph was allowed to edit to see actual changes.

Writing instructions.md

The instructions.md file defines Ralph's behavior for a run. Key elements:

1. Role definition — What is Ralph doing? (Refining stories, writing code, reviewing, ...)
2. One-task-per-iteration rule — Always enforce this. Without it, the model tries to do everything at once and produces lower-quality results.
3. Startup sequence — Which files to read and in what order. This is Ralph's "memory load." Use {{RUN_DIR}} for run-specific files.
4. Task selection priorities — A strict priority list. Ralph picks the first applicable task, does it, and stops.
5. File ownership table — What Ralph may read vs. write. Prevents accidental overwrites.
6. Completion signal — How Ralph signals that all work is done (<promise>COMPLETE</promise>).
7. Guardrails — Rules to prevent Ralph from making unauthorized decisions.

Best Practices

Do

• Keep iterations small. One task per iteration produces better results than batching.
• Use progress.txt as memory. Ralph reads it every iteration. Be explicit about what was done and what was deferred.
• Clean up chief-wiggum.md between runs. Remove addressed items to avoid confusion.
• Review diffs after the loop. Ralph is autonomous but not infallible. Spot-check the changes.
• Use the right model. Opus for complex reasoning tasks, Sonnet for straightforward work.
• Match tools to the task. Read/Edit/Write for spec work. Add Bash/Glob/Grep for coding tasks.

Don't

• Don't modify files Ralph owns during a run. File conflicts will confuse the model.
• Don't give Ralph tools it doesn't need. Minimal tool sets reduce unintended side effects.
• Don't expect Ralph to remember across iterations. Every iteration is a fresh context. If it's not in a file, it doesn't exist.
• Don't skip instructions.md. Running without a structured prompt loses the task selection that makes Ralph reliable.