ralpher 0.1.5

Ralph Wiggum Loop engine for Claude Code

Ralpher

A CLI tool that orchestrates Claude Code for autonomous software development. Give it a prompt, and it generates a Project Plan, breaks it into tasks, then runs iterative Claude development loops to implement each one.

Workflow: User Prompt ➔ Project Plan ➔ Ralph Wiggum Loop⁠

Install

pipx install ralpher

Usage

# 1. Generate a Project Plan
ralpher plan "Create a TODO app" --name todo-app

# (Optional) Refine the plan
ralpher refine "Use MySQL"

# 2. Run the Ralph-loop on an existing plan
ralpher loop

How it works

1. Plan generation -- Sends your prompt to Claude to produce a structured Project Plan with tasks, saved to .ralpher/projects/{project_id}/PLAN.md.
2. Run Ralph-loop
   1. Parses the plan into a structured JSON model (project, tasks with acceptance criteria and priorities).
   2. Iteratively invokes claude to implement each task on a dedicated git branch (ralph/{project_id}), tracking progress and detecting completion.

Notion integration

Ralpher supports optional Notion integration for syncing task status. Set these in a .env file:

• RALPHER_NOTION_TOKEN -- Notion API token
• RALPHER_NOTION_PARENT_PAGE_ID -- Parent page for task pages

Development

# Run tests
uv run pytest

TODO

• Add git worktree support
• Create PRs automatically
• Run repeating tasks in a loop (useful for continuous optimization, refactoring, or research)
• Implement a standalone reviewer agent (or subagent) in both the planning and loop stages
• Support Gemini-CLI
• Support Codex CLI

Acknowledgements

This project draws its design and some of its prompts from snarktank/ralph.