Ralph Loop - Autonomous Claude Development

A working workaround for the broken ralph-wiggum Claude Code plugin. Enables autonomous AI development iterations with timing stats and automatic completion detection.

Why This Exists

The official ralph-wiggum plugin (v2.0.76+) has critical bugs:

• Multi-line bash commands blocked by security checks
• /cancel-ralph command doesn't work
• Stop hook hijacks all sessions

This script bypasses those issues entirely.

How It Works

┌─────────────────────────────────────────────────────────┐
│                    ralph-loop.sh                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   1. Read .claude/RALPH_PROMPT.md                       │
│   2. Combine with CLAUDE.md (if exists)                 │
│   3. Run: claude -p --dangerously-skip-permissions      │
│   4. Check output for <promise>...</promise>            │
│   5. If found → exit success                            │
│   6. If not → increment iteration, goto 1               │
│                                                         │
│   Stops when:                                           │
│   - Completion promise detected                         │
│   - Max iterations reached                              │
│   - Ctrl+C pressed                                      │
│   - Prompt file deleted                                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Each iteration runs a fresh Claude session with the same prompt. Claude sees its previous work in the filesystem, allowing iterative improvement.

Setup

your-project/
├── ralph-loop.sh           # The loop script
├── CLAUDE.md               # Project context (optional)
├── README.md
└── .claude/
    └── RALPH_PROMPT.md     # Your task prompt (required)

Usage

1. Customize the prompt

   # Edit .claude/RALPH_PROMPT.md with your task

2. Run the loop (from a separate terminal, not inside Claude Code)

   ./ralph-loop.sh           # Default: 50 iterations
   ./ralph-loop.sh 20        # Custom: 20 iterations

3. Monitor progress

   • Watch the terminal output
   • Check generated files
   • View PROGRESS.md for work log

4. Stop early

   • Ctrl+C to interrupt
   • Delete .claude/RALPH_PROMPT.md to trigger safe exit

Completion Promise

The loop detects completion via XML tags in Claude's output:

## Completion Criteria

When all tests pass, output: <promise>COMPLETE</promise>

When Claude outputs this tag, the script exits with success.

Writing Good Prompts

Do

• Be specific about success criteria
• Include validation steps (run tests, check output)
• List files to preserve
• Set reasonable iteration limits

Don't

• Use vague completion criteria
• Forget to mention test commands
• Skip the "Files to KEEP" section

Example Structure

# Task Title

[Clear description of what to build]

## Requirements
- Requirement 1
- Requirement 2

## Completion Criteria
When ALL of the following are true:
- Tests pass (`npm test`)
- Server runs (`npm start`)

Output: <promise>DONE</promise>

Cost Estimates

Iterations	Estimated Cost
10	$15 - $25
25	$40 - $70
50	$75 - $150+

Costs vary based on task complexity and output length.

Comparison

Feature	Broken Plugin	This Script
Execution	Inside session	External bash
Permissions	Blocked	Bypassed
Cancel	Broken	Ctrl+C works
Stats	None	Full timing
Reliability	Fails	Works

Troubleshooting

Issue	Solution
"RALPH_PROMPT.md not found"	Create .claude/RALPH_PROMPT.md
Loop runs forever	Add --max-iterations or clearer completion criteria
Claude doesn't see previous work	Ensure files are saved, not just planned
High costs	Reduce iterations, simplify prompt

Credits

• Original Ralph technique: ghuntley.com/ralph
• Script source: mjohnson518/claude_superpowers