oh-my-ralph 0.5.0

An opinionated orchestrator for Ralph Wiggum loops

oh-my-ralph: Ralph Wiggum Loop Orchestrator

      ⠀⠀⠀⠀⠀⠀⣀⣤⣶⡶⢛⠟⡿⠻⢻⢿⢶⢦⣄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢀⣠⡾⡫⢊⠌⡐⢡⠊⢰⠁⡎⠘⡄⢢⠙⡛⡷⢤⡀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢠⢪⢋⡞⢠⠃⡜⠀⠎⠀⠉⠀⠃⠀⠃⠀⠃⠙⠘⠊⢻⠦⠀⠀⠀⠀⠀⠀
⠀⠀⢇⡇⡜⠀⠜⠀⠁⠀⢀⠔⠉⠉⠑⠄⠀⠀⡰⠊⠉⠑⡄⡇⠀⠀⠀⠀⠀⠀
⠀⠀⡸⠧⠄⠀⠀⠀⠀⠀⠘⡀⠾⠀⠀⣸⠀⠀⢧⠀⠛⠀⠌⡇⠀⠀⠀⠀⠀⠀
⠀⠘⡇⠀⠀⠀⠀⠀⠀⠀⠀⠙⠒⠒⠚⠁⠈⠉⠲⡍⠒⠈⠀⡇⠀⠀⠀⠀⠀⠀
⠀⠀⠈⠲⣆⠀⠀⠀⠀⠀⠀⠀⠀⣠⠖⠉⡹⠤⠶⠁⠀⠀⠀⠈⢦⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠈⣦⡀⠀⠀⠀⠀⠧⣴⠁⠀⠘⠓⢲⣄⣀⣀⣀⡤⠔⠃⠀⠀⠀⠀⠀
⠀⠀⠀⠀⣜⠀⠈⠓⠦⢄⣀⣀⣸⠀⠀⠀⠀⠁⢈⢇⣼⡁⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢠⠒⠛⠲⣄⠀⠀⠀⣠⠏⠀⠉⠲⣤⠀⢸⠋⢻⣤⡛⣄⠀⠀⠀⠀⠀⠀⠀
⠀⠀⢡⠀⠀⠀⠀⠉⢲⠾⠁⠀⠀⠀⠀⠈⢳⡾⣤⠟⠁⠹⣿⢆⠀⠀⠀⠀⠀⠀
⠀⢀⠼⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⠃⠀⠀⠀⠀⠀⠈⣧⠀⠀⠀⠀⠀
⠀⡏⠀⠘⢦⡀⠀⠀⠀⠀⠀⠀⠀⠀⣠⠞⠁⠀⠀⠀⠀⠀⠀⠀⢸⣧⠀⠀⠀⠀
⢰⣄⠀⠀⠀⠉⠳⠦⣤⣤⡤⠴⠖⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢯⣆⠀⠀⠀
⢸⣉⠉⠓⠲⢦⣤⣄⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⣠⣼⢹⡄⠀⠀
⠘⡍⠙⠒⠶⢤⣄⣈⣉⡉⠉⠙⠛⠛⠛⠛⠛⠛⢻⠉⠉⠉⢙⣏⣁⣸⠇⡇⠀⠀
⠀⢣⠀⠀⠀⠀⠀⠀⠉⠉⠉⠙⠛⠛⠛⠛⠛⠛⠛⠒⠒⠒⠋⠉⠀⠸⠚⢇⠀⠀
⠀⠀⢧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⠇⢤⣨⠇⠀
⠀⠀⠀⢧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⢻⡀⣸⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⠛⠉⠁⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⢠⢄⣀⣤⠤⠴⠒⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀
⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠘⡆⠀⠀⠀⠀⠀
⠀⠀⠀⡎⠀⠀⠀⠀⠀⠀⠀⠀⢷⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀
⠀⠀⢀⡷⢤⣤⣀⣀⣀⣀⣠⠤⠾⣤⣀⡘⠛⠶⠶⠶⠶⠖⠒⠋⠙⠓⠲⢤⣀⠀
⠀⠀⠘⠧⣀⡀⠈⠉⠉⠁⠀⠀⠀⠀⠈⠙⠳⣤⣄⣀⣀⣀⠀⠀⠀⠀⠀⢀⣈⡇
⠀⠀⠀⠀⠀⠉⠛⠲⠤⠤⢤⣤⣄⣀⣀⣀⣀⡸⠇⠀⠀⠀⠉⠉⠉⠉⠉⠉⠁⠀
  Credit: https://emojicombos.com/ralph-wiggum-ascii-art
  

Ralph Wiggum Orchestrator

This is a simple orchestrator for Ralph Wiggum loop invented by Geoffrey Huntley.

Supports

1. Claude Code
2. Github Copilot
3. Opencode
4. Amp
5. Any other tool that you can call from CLI (Experimental)

Requirements

Python 3.10+

How to run?

1. Install the package

   pip install oh-my-ralph
   

2. Place a requirements.md file with your detailed requirements in your working directory (where you want the software to be built)
3. Choose an AI agent and run the Ralph Loop with the appropriate command below.

Using with Claude Code

Claude Code offers Anthropic's Claude models with advanced coding capabilities.

Prerequisites:

• Install Claude Code: Follow instructions at https://code.claude.com

oh-my-ralph --agent "claude -p" --model sonnet --working-dir /path/to/dir/with/requirements

Note: The --dangerously-skip-permissions flag is automatically added to enable all permissions for seamless operation.

Using with AMP (Sourcegraph)

AMP provides powerful AI assistance with multi-model support and advanced coding capabilities.

Prerequisites:

• Install AMP: npm install -g @sourcegraph/amp@latest or use npx --yes @sourcegraph/amp

oh-my-ralph --agent "npx --yes @sourcegraph/amp" --model smart --working-dir /path/to/dir/with/requirements

Note: The --dangerously-allow-all flag is automatically added to enable all permissions for seamless operation.

Features:

• Multi-model support (Claude Opus 4.6, GPT-5.2, fast models)
• Advanced coding capabilities with subagents and oracle mode
• Seamless integration with development workflows
• Automatic permission handling with --dangerously-allow-all flag for uninterrupted operation

Using with OpenCode

OpenCode is the default agent and provides a web interface for monitoring progress.

oh-my-ralph --agent "opencode run" --model opencode/glm-4.7-free --start-opencode-web-at-port 8089 --working-dir /path/to/dir/with/requirements

Features:

• Web dashboard at http://localhost:8089
• Supports various OpenCode models
• Real-time progress monitoring
• Automated permission handling for seamless operation

Using with GitHub Copilot CLI

GitHub Copilot CLI provides powerful AI assistance with access to GitHub's Copilot models.

Prerequisites:

• Install GitHub Copilot CLI: https://docs.github.com/en/copilot/github-copilot-in-the-cli/quickstart

oh-my-ralph --agent "copilot -p" --model gpt-4 --working-dir /path/to/dir/with/requirements

Note: The --yolo flag is automatically added to enable all permissions for seamless operation.

Features:

• Access to GPT-4 and other Copilot models
• Non-interactive execution per iteration
• Seamless integration with GitHub ecosystem
• Automatic permission skipping with --yolo flag for uninterrupted automation
• Runs your specified agent command in a loop.
• The loop exits when any of the following occur:
  • The command prints <PROMPT>DONE</PROMPT>.
  • The maximum number of iterations is reached, configurable via --max-iterations.
  • Error occurs for 5 consecutive runs of the loop.
  • You manually stop the process by pressing Ctrl+C.

Development

Running Tests

Tests are automatically run during the build process. To run tests manually:

If you have pytest installed

pytest

If you don't have pytest installed

python test_ralph.py -v
python test_cli_model_required.py -v

All tests must pass before building.