ralph

Ralph

Braindead agentic loop that iteratively works toward a goal until done or time expires. Named after Ralph Wiggum - just keep trying until it works.

Philosophy

No sophisticated planning. No complex orchestration. Just:

1. Read the goal
2. Try to make progress
3. Commit progress
4. Repeat until DONE

History provides learning without complex state management. Time budget prevents runaway costs.

Usage

.claude/harness/ralph/run \
  --goal=path/to/goal.md \
  [--duration=4h] \
  [--model=sonnet] \
  [--reasoning=low] \
  [--spinner] \
  [--continue] \
  [--no-art]

Flags:

• --goal - Path to goal markdown file (required)
• --duration - Time budget (e.g., 4h, 200m); unlimited if omitted
• --model - haiku, sonnet, opus (default: sonnet)
• --reasoning - none, low, med, high (default: med)
• --spinner - Enable progress spinner (off by default)
• --continue - Continue from existing progress
• --no-art - Suppress ASCII art in header

Reasoning levels (fraction of model's max thinking budget):

• none = 0 (no thinking)
• low = 25% of max
• med = 50% of max
• high = 100% of max

Goal File Format

Use /load goal-authoring for guidance on writing effective goals.

File naming convention: Goal files MUST be named: <name>-ralph-goal.md

Examples:

• list-tool-ralph-goal.md ✓
• web-fetch-ralph-goal.md ✓
• list-tool-goal.md ✗ (missing "ralph")
• list-tool.md ✗ (missing "ralph-goal")

Required sections:

• ## Objective - What to achieve (outcomes, not steps)
• ## Reference - All relevant plan/research/user-story docs
• ## Outcomes - Measurable, verifiable outcomes
• ## Acceptance - Success criteria (make check, tests, etc.)

State files are derived from the goal file name:

• <name>-ralph-goal.md → <name>-ralph-progress.jsonl, <name>-ralph-summary.md
• Example: web-fetch-ralph-goal.md produces:
  • web-fetch-ralph-progress.jsonl
  • web-fetch-ralph-summary.md

Progress File Format

JSONL (one JSON object per line):

{"iteration":1,"timestamp":"2026-01-11T08:37:27-06:00","progress":"Removed tool_dispatcher.c from Makefile"}
{"iteration":2,"timestamp":"2026-01-11T08:42:49-06:00","progress":"Deleted src/tool_bash.c and updated headers"}
{"iteration":3,"timestamp":"2026-01-11T08:51:20-06:00","progress":"DONE"}

Fields:

• iteration - Iteration number
• timestamp - ISO 8601 timestamp
• progress - What was accomplished or DONE when complete

Summary File

Auto-generated markdown summarizing progress. Updated every 10 iterations by a summarizer agent. Provides condensed context for the worker agent without loading full history.

Loop Behavior

1. Validate - Ensure goal file has ## Objective section
2. Initialize - Create empty progress/summary files (or load if --continue)
3. Handle dirty state - If working copy has changes, commit them
4. Work iteration - Agent reads goal + history, makes progress, returns progress string
5. Commit - Changes committed via jj commit
6. Record - Progress appended to progress file
7. Summarize - Every 10 iterations, summarizer condenses history
8. Repeat - Until DONE returned or time expires

Termination:

• Agent returns DONE
• Time budget expires
• Manual interrupt (Ctrl+C)

Writing Effective Goals

See /load goal-authoring for comprehensive guidance. Key insight: Ralph has unlimited context through iteration - write complete objectives with all relevant references, specify outcomes (not steps), and trust Ralph to discover the implementation path.

Tips

• Start with generous time budget - ralph may need multiple iterations
• Use --continue to resume after interruption
• Check progress file to see what's been accomplished
• Goal files should be outcome-focused, not action-focused
• Trust the agent to discover implementation details