Skip to main content

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 .claude/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.

Metadata

Release files for ralpher 0.1.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ralpher 0.1.6
File Size Uploaded Provenance Actions
ralpher-0.1.6.tar.gz 59.0 kB Without provenance Details for ralpher-0.1.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ralpher 0.1.6
File Interpreter ABI Platform Actions
ralpher-0.1.6-py3-none-any.whl Python 3 none any Details for ralpher-0.1.6-py3-none-any.whl

Total release size: 98.4 kB

Release files / ralpher-0.1.6.tar.gz

Download URL ralpher-0.1.6.tar.gz
Size 59.0 kB
Tags Source
SHA-256 checksum
How to use checksums
3559113db475d2f98851e94e3dec9efc9de63d214c07b260d95fbdfa3207f18c
BLAKE2b-256 checksum
How to use checksums
5a7961163604b4b861be2a8f9f21d5f559954759fbd7f266bc2db67a8123fc63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ralpher-0.1.6-py3-none-any.whl

Download URL ralpher-0.1.6-py3-none-any.whl
Size 39.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
425a3eacfb084744da2ca993de4f5bc467af9ac5f6b585f0c5d0d18484fc68c3
BLAKE2b-256 checksum
How to use checksums
e811f56fba62f58f59b4116f81f2b9075dbb33f4b544668f1b324f7333360fb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ralpher 0.1.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page