RALPHIO is a minimal AI-driven development orchestrator inspired by the Ralph Wiggum Technique and repomirror. It embodies the philosophy that "less is more" - focusing on the engine rather than the scaffolding. By running AI in a continuous loop with strict constraints ("one task per loop"), RALPHIO achieves remarkable development automation with just ~800 lines of Node.js code.
RALPHIO follows three core principles:
- One Task Per Loop - Borrowed from the Ralph Wiggum Technique, each loop handles exactly one task (1-2 story points) to manage context effectively
- Minimal Scaffolding - Inspired by repomirror's approach, we focus on the core engine rather than complex orchestration
- Continuous Iteration - Tasks are processed sequentially with automatic commits, memory updates, and learnings
The result is a tool that can autonomously handle development tasks, from simple file creation to complex feature implementation with Test-Driven Development (TDD) support.
- 🎯 One Task Per Loop - Processes exactly one task per execution, maintaining focus and context
- 🧪 TDD Support - Built-in Test-Driven Development workflow (write tests → implement → verify)
- 📝 PRD Parsing - Convert Product Requirements Documents into actionable tasks
- 🔄 Multi-Loop Execution - Run continuously until all tasks complete
- 💾 Auto-Commit - Automatic git commits with descriptive messages
- 🧠 Memory System - Persistent learnings across loops to avoid repeated mistakes
- 📊 Rich Logging - Detailed logs for debugging and progress tracking
- ⏱️ Timeout Protection - Configurable timeouts with graceful failure handling
npm install -g ralphiogit clone https://github.com/onorbumbum/ralphio.git
cd ralphio
npm installralphio initThis creates the .agent/ directory structure:
.agent/planning.md- Task list with checkboxes.agent/memory.md- Persistent memory and learnings.agent/prompt.md- System prompt (customizable).agent/agent.config.json- Configuration file
Edit .agent/planning.md with your tasks:
# Project Tasks
## Feature Development
- [ ] Create user authentication system
- [ ] Add database models for users
- [ ] Implement login API endpoint
- [ ] Create login UI component
- [ ] Add session managementSingle task execution:
ralphio --onceRun until all tasks complete:
ralphio --until-successParse a PRD into tasks:
ralphio --parse-prd requirements.mdRALPHIO operates in a simple loop:
- Read - Reads the first unchecked task from
.agent/planning.md - Plan - Uses AI to create an implementation plan
- Execute - Implements the task following the plan
- Verify - Runs
npm run buildor tests to verify the implementation - Update - Marks task complete and updates memory with learnings
- Commit - Auto-commits changes with descriptive message
Each loop is self-contained and atomic, ensuring clean state management and traceable progress.
RALPHIO supports Test-Driven Development with a two-phase approach:
When encountering a task without [TEST] or [IMPLEMENT] markers:
- Writes failing tests based on requirements
- Commits tests with
test: <task>message - Marks task complete and adds
[IMPLEMENT]task
When encountering [IMPLEMENT] task:
- Implements code to pass the tests
- Iterates until all tests pass
- Commits implementation with
feat: <task>message
LOOP_TIMEOUT_MS- Set loop timeout (default: 600000ms = 10 minutes)
LOOP_TIMEOUT_MS=180000 ralphio --once # 3 minute timeoutRALPHIO maintains learnings in .agent/memory.md:
## Stack Discovery
- **Stack**: TypeScript, Next.js 14, React
- **Build Command**: npm run build
- **Type Check**: npm run typecheck
## Learnings
- Next.js 15.4: Route params are Promise<{id: string}> - must await
- Chakra v3: Button doesn't support leftIcon - use children insteadThese learnings persist across loops, preventing repeated mistakes.
Edit .agent/prompt.md to customize RALPHIO's behavior. The default prompt enforces:
- One task per loop
- Read before edit
- Build verification
- Memory updates for key learnings
RALPHIO automatically breaks down large tasks (>2 story points):
Original task:
- [ ] Create calendar with Google integration
Becomes:
- [x] Create calendar with Google integration (broken down)
- [ ] Install calendar dependencies
- [ ] Create basic calendar component
- [ ] Add Google Calendar API setup
- [ ] Wire up calendar to main page- 3 consecutive failures - Stops execution to prevent infinite loops
- 50 iteration limit - Safety limit for long-running sessions
- Timeout protection - Graceful handling of stuck operations
ralphio init # Initialize .agent/ structure
ralphio --once # Run single task
ralphio --until-success # Run until all tasks complete
ralphio --parse-prd <file> # Parse PRD into tasks
ralphio --version # Show version
ralphio --help # Show helpyour-project/
├── .agent/
│ ├── agent.config.json # Configuration
│ ├── planning.md # Task list
│ ├── memory.md # Persistent learnings
│ ├── prompt.md # System prompt
│ ├── artifacts/ # Loop artifacts
│ └── logs/ # Daily logs
└── your-code/
"No unchecked tasks found"
- Add tasks with
- [ ]format to.agent/planning.md
Build failures
- Ensure your project has a working
npm run buildcommand - Check
.agent/memory.mdfor stack discovery
Git commit failures
- Configure git with user.name and user.email
- Ensure you have a git repository initialized
Timeout issues
- Increase
LOOP_TIMEOUT_MSfor complex tasks - Break down large tasks into smaller subtasks
Check these locations for debugging:
.agent/logs/ralphio_YYYY-MM-DD.log- Human-readable activity log.agent/memory.md- Persistent learnings and stack info- Git history - Each task creates descriptive commits
Traditional AI coding assistants require constant human intervention. RALPHIO changes this by:
- Autonomous Operation - Runs without human intervention for hours
- Context Management - "One task per loop" prevents context overflow
- Self-Correction - Learns from failures and updates approach
- Traceable Progress - Every change is committed with context
- Minimal Complexity - ~800 lines of code vs thousands in alternatives
RALPHIO embraces simplicity. When contributing:
- Follow the "one task per loop" principle
- Maintain the minimal philosophy (KISS/DRY/YAGNI)
- Resist adding complex features
- Focus on reliability over features
MIT
RALPHIO stands on the shoulders of giants:
- Ralph Wiggum Technique - For the "one task per loop" philosophy and continuous AI iteration approach
- repomirror - For proving that "less is more" in AI orchestration
- Claude Task Master - For the successful PRD parsing approach that inspired our implementation
- Claude Code SDK - For providing the AI engine that powers RALPHIO
- Issues: GitHub Issues
- Documentation: This README and
.agent/prompt.md - Philosophy: Keep it simple, one task at a time
"Any problem created by AI can be resolved through a different series of prompts" - The Ralph Wiggum Technique