A self-improving task orchestrator for AI-assisted development. Based on Ralph Wiggum concept.
rralph automates an iterative, AI-assisted development workflow. It reads your project's plan, learnings, and todo list, then orchestrates AI tool invocations to complete tasks one by one — learning, testing, and committing along the way.
gem install rralph
Ralph by default uses qwen-code as the AI agent. You can override this with the --ai-command flag.
Before running rralph, ensure you have:
- A Git repository initialized
- Three Markdown files in your working directory:
plan.md— Your high-level project planlearnings.md— Accumulated insights (can start empty)todo.md— Task list with checkboxes (one task per line, can be empty first, rralph will generate the tasks)
Example plan.md:
Plan: Bash script that prints "IS EVEN" or "IS ODD" based on input.
Input: One integer as command-line argument.
Output: "IS EVEN" if divisible by 2, "IS ODD" otherwise.
Error: If no argument or non-integer, print error and exit 1.
Logic: Use % to check remainder. Validate input with regex: ^-?[0-9]+$.
File: odd_even.sh
Requirements:
- Need to be in bash
- Validate input
- Use conditional with (( ))
- No external tools
Test: 0→EVEN, 7→ODD, -4→EVEN, abc→error, no arg→errorAfter running rralph start you will get a todo.md generated for you like:
# Todo List
- [ ] Create `odd_even.sh` file with bash shebang
- [ ] Add input validation to check if argument is provided
- [ ] Add regex validation for integer input (`^-?[0-9]+$`)
- [ ] Implement even/odd check using `(( ))` arithmetic and `%` operator
- [ ] Print "IS EVEN" or "IS ODD" based on result
- [ ] Add error handling with exit code 1 for invalid inputs
- [ ] Make script executable with `chmod +x`
- [ ] Test with input `0` (expect "IS EVEN")
- [ ] Test with input `7` (expect "IS ODD")
- [ ] Test with input `-4` (expect "IS EVEN")
- [ ] Test with input `abc` (expect error, exit 1)
- [ ] Test with no argument (expect error, exit 1)
Run rralph with default settings:
rralphOr with options:
rralph --max-failures 2 --watch➜ rralph help
Commands:
rralph help [COMMAND] # Describe available commands or one specific command
rralph start # Run the rralph orchestrator
rralph stats # Show progress statistics
rralph tree # Print a tree of all available commands
rralph version # Show rralph version
➜ rralph help start
Usage:
rralph start
Options:
-m, [--max-failures=N] # Maximum allowed failures before stopping
# Default: 3
-a, [--ai-command=AI_COMMAND] # AI command to invoke
# Default: qwen-code -y -s -o stream-json
-w, [--watch], [--no-watch], [--skip-watch] # Run in continuous loop until completion or max failures
# Default: false
-p, [--plan-path=PLAN_PATH] # Path to plan.md file
# Default: plan.md
-l, [--learnings-path=LEARNINGS_PATH] # Path to learnings.md file
# Default: learnings.md
-t, [--todo-path=TODO_PATH] # Path to todo.md file
# Default: todo.md
-s, [--skip-commit], [--no-skip-commit] # Skip git commits between tasks
# Default: false
-v, [--verbose], [--no-verbose] # Enable verbose logging with AI thinking and real-time output
# Default: false
Run a single cycle:
rralphRun continuously until all tasks are done or max failures reached:
rralph start --watch --max-failures 5Use a custom AI command (e.g claude-code-router + claude-code):
rralph start --ai-command "ccr code"Skip git commits between tasks (files are updated but not committed):
rralph start --skip-commitView progress statistics:
$> rralph stats
Tasks: 5/6 done
Pending: 1
Learnings: 6 lines- Read —
rralphreadsplan.md,learnings.md, andtodo.md - Prompt — Builds a prompt with file contents and sends to LLM
- Parse — Analyzes AI response for:
TASK_FAILUREkeyword (case-sensitive, whole word)- New learnings to extract
- Update — On success:
- Marks current task as complete in
todo.md - Appends new learnings to
learnings.md - Commits all changes to Git
- Marks current task as complete in
- Repeat — In
--watchmode, continues until done or max failures
- Each
TASK_FAILUREresponse increments a counter - Non-failure responses reset the counter to 0
- When max failures reached,
rralphexits with error: -
Max failures reached (N). Stopping to avoid infinite loops. Review learnings.md and todo.md.
By default, rralph outputs concise progress logs to stderr:
Starting rralph with max_failures=3, ai_command='qwen-code -y -s'
Cycle 1: Processing task: Create odd_even.sh file with bash shebang
Executing AI command...
Completed in 2341ms (13407 tokens)
[Cycle 1] Task completed. 0 failures. Git commit: abc123
Log saved: logs/cycle_1_20260302_145738.md
Use --verbose mode for detailed real-time logging including AI thinking:
rralph start --verboseVerbose output shows:
- Thinking: AI's thought process as it thinks
- Real-time text output from the AI
- Completion metrics (duration, token usage)
Example verbose output:
Executing AI command...
Thinking: The user wants me to create a bash script for checking even/odd numbers
Thinking: I need to start with the basic file structure and shebang
I'll create the odd_even.sh file with a proper bash shebang.
Completed in 1847ms (8234 tokens)
In --watch mode, full AI responses are saved to logs/ for audit trail.
Available as open source under the terms of the MIT License.