An implementation of the Ralph Wiggum iterative development technique using CrewAI Flows + Crews.
Ralph Wiggum is a development methodology based on continuous AI loops:
while not done:
plan() # Decide what to do next
develop() # Make a small code change
verify() # Run tests and checks
The AI sees its previous work, learns from failures, and iteratively improves until all criteria pass.
# Install dependencies
pip install -r requirements.txt
# Set up API key
cp .env.example .env
# Edit .env with your OPENAI_API_KEY
# Run Ralph
python main.py "Create an add function with tests" --max-iterations 10ralph_crewai/
├── main.py # CLI entry point
├── requirements.txt # Dependencies
├── .env.example # Environment template
├── GUIDE.md # Detailed beginner guide
├── src/
│ ├── __init__.py
│ ├── models.py # Pydantic state models
│ ├── tools.py # CrewAI tools (file ops, testing)
│ ├── agents.py # Agent definitions
│ └── flow.py # The Ralph Flow implementation
├── config/
│ ├── agents.yaml # Agent configuration
│ └── tasks.yaml # Task templates
└── examples/
├── simple_math.txt # Basic math library objective
├── todo_api.txt # API building objective
└── bug_fix.txt # Bug fixing objective
# Inline objective
python main.py "Your objective here" --max-iterations 25
# From file
python main.py --file examples/simple_math.txt --max-iterations 50
# Custom completion promise
python main.py "Fix all bugs" --promise "BUGS_FIXED" --max-iterations 20from src.flow import run_ralph
result = run_ralph(
objective="Build a todo API with tests",
max_iterations=25,
completion_promise="RALPH_COMPLETE"
)- PlannerAgent - Breaks the objective into atomic tasks
- DeveloperAgent - Implements one small change at a time
- VerifierAgent - Runs pytest, ruff, and TODO scans
- Flow Controller - Routes to completion or loops back
Ralph completes when ALL of these pass:
- All tests pass (pytest)
- Zero lint errors (ruff)
- No TODO/FIXME comments
- Clean exit state
See GUIDE.md for a complete beginner-friendly guide.