Ralph: Autonomous AI Agent Loop
The "Wiggum loop" -- forces the agent to iterate through product requirements until all PRD items are complete. 19k stars, MIT licensed, primarily TypeScript.
Core Architecture
Each iteration creates a new AI context window with clean state. Continuity via: - Git commit history from previous runs - progress.txt (learnings appended across iterations) - prd.json (tracks story completion status)
Workflow Loop
- Read highest-priority incomplete story from prd.json
- Spawn fresh AI instance with prompt + codebase context
- Implement single story
- Execute quality checks (typecheck, tests)
- Commit changes if checks pass
- Mark story passes: true in prd.json
- Append findings to progress.txt
- Repeat until all stories complete or iteration limit reached
Key Components
| File | Function |
|---|---|
| ralph.sh | Bash orchestrator (--tool amp or --tool claude) |
| prompt.md / CLAUDE.md | Tool-specific prompts |
| prd.json | Machine-readable task list with completion flags |
| progress.txt | Append-only knowledge base for future iterations |
Critical Design Patterns
- Right-Sized Stories: Tasks must fit single context windows
- AGENTS.md Documentation: Each iteration updates docs with discovered patterns
- Feedback Loops Required: typecheck, tests, CI catch errors immediately
- Browser Verification: Frontend stories invoke dev-browser skill
Notable Features
- Automatic context handoff when Amp fills
- Archive system preserving previous runs by branch/date
- Interactive flowchart visualization
- Support for both Amp and Claude Code