Ralph Wiggum

A harness generator for creating agentic coding loops with Claude Code.

Quick Start

curl -sL https://raw.githubusercontent.com/pauley-unsaturated/RalphWiggum/main/init.sh | bash -s /path/to/your/repo

Or clone and run locally:

git clone https://github.com/pauley-unsaturated/RalphWiggum.git
./RalphWiggum/init.sh /path/to/your/repo

What is This?

Ralph Wiggum generates scaffolding that lets Claude Code work autonomously on your codebase in an infinite loop. The pattern comes from the YC Agents hackathon, where teams discovered that running Claude in a simple loop with a focused prompt could accomplish large-scale code transformations overnight.

The core idea:

while :; do cat prompt.md | claude -p --dangerously-skip-permissions; done

This repo wraps that pattern with:

• Issue tracking via markdown files (TODO.md, NOTES.md, STATUS.md)
• Test-driven validation requiring build/lint/test to pass before commits
• Code critic for identifying tech debt and code quality issues
• Auto-detection of project types and appropriate commands

Usage

Initialize a Repository

./init.sh /path/to/your/repo

This copies the generator and runs it, creating all necessary files. Then follow the printed instructions.

Manual Setup

If you prefer more control:

./wiggum init --target-dir /path/to/repo --description "Your project goal"

Options:

--target-dir DIR        Target repository (default: current directory)
--project-name NAME     Project name (default: directory name)
--description DESC      Project goal for the agent
--test-command CMD      Test command (default: auto-detect)
--build-command CMD     Build command (default: auto-detect)
--lint-command CMD      Lint command (default: auto-detect)

Run the Loop

cd /path/to/your/repo

# Single iteration (test first)
./sync.sh

# Infinite loop
./ralph.sh

# Code review pass
./critic.sh

Press Ctrl+C to stop the loop at any time.

Generated Files

your-repo/
├── .agent/
│   ├── TODO.md          # Task list - agent picks from here
│   ├── NOTES.md         # Agent's scratchpad and observations
│   └── STATUS.md        # Progress tracking
├── prompt.md            # Main loop prompt (customize this!)
├── critic.md            # Code review prompt
├── sync.sh              # Run single iteration
├── ralph.sh             # Run infinite loop
└── critic.sh            # Run code critic

Customization

Edit prompt.md

The most important file. Update the Objective section with your specific goal:

## Objective
Convert this Python REST API to use FastAPI instead of Flask

Edit .agent/TODO.md

Add your initial work items:

## High Priority
- [ ] Replace Flask imports with FastAPI
- [ ] Convert route decorators to FastAPI style
- [ ] Update request/response handling

Configure Commands

If auto-detection got it wrong, update the validation commands in prompt.md:

4. **Validate** your changes:
   - Build: `npm run build`
   - Lint: `npm run lint`
   - Test: `npm test`

How It Works

1. Agent reads TODO.md and picks the highest priority task
2. Agent implements the change with minimal modifications
3. Agent validates by running build, lint, and test commands
4. Agent commits if validation passes
5. Agent updates TODO.md and STATUS.md
6. Loop repeats

The agent maintains context through the .agent/ directory, allowing it to track progress across iterations.

Code Critic

Run ./critic.sh periodically to have Claude review the codebase for:

• Security issues
• Performance problems
• Code duplication
• Missing tests
• Tech debt

Issues found are added to TODO.md under "Tech Debt".

Project Type Detection

The generator auto-detects these project types and configures appropriate commands:

Type	Detection	Test Command
Node.js	package.json	npm test
Rust	Cargo.toml	cargo test
Go	go.mod	go test ./...
Python	pyproject.toml, setup.py, requirements.txt	pytest
Ruby	Gemfile	bundle exec rspec
Java	pom.xml, build.gradle	mvn test / gradle test
Elixir	mix.exs	mix test

Tips

• Simple prompts work better - The original hackathon found that 103 words outperformed 1,500 words
• Commit often - The agent makes atomic commits after each change
• Let it self-regulate - Agents naturally stop or focus on tests when main work is done
• Review periodically - Check STATUS.md and recent commits to monitor progress
• Run critic passes - Periodic code review keeps quality high

Requirements

• Claude Code CLI (claude command)
• Git
• Bash 4.0+

License

MIT

Acknowledgments

Inspired by Geoff Huntley's agentic coding patterns and the YC Agents hackathon teams who pioneered the "Ralph loop" technique.