Metadata-Version: 2.4
Name: ralphx
Version: 0.4.2
Summary: Autonomous AI loop orchestration for Claude Code - define workflows in YAML, run autonomously, monitor in real-time
Project-URL: Homepage, https://github.com/jackneil/ralphx
Project-URL: Repository, https://github.com/jackneil/ralphx
Project-URL: Documentation, https://github.com/jackneil/ralphx#readme
Author-email: Jack Neil <jack@jackmd.com>
License-Expression: MIT
Keywords: agent,ai,automation,claude,llm,orchestration,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sse-starlette>=1.0
Requires-Dist: typer>=0.9
Requires-Dist: uvicorn[standard]>=0.20
Requires-Dist: watchfiles>=0.20
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# RalphX

![RalphX Demo](https://raw.githubusercontent.com/jackneil/ralphx/main/docs/images/ralphx-demo.gif)

**From idea to working, tested code. Autonomously.**

RalphX is a **Ralph wrapper** for managing Ralph loops across your entire product development lifecycle. [Ralph](https://github.com/anthropics/claude-code) is the viral Claude Code looping pattern - RalphX orchestrates multiple Ralph loops together: research an idea, generate a design doc, write user stories, implement features, and test everything. Each Ralph loop runs with fresh context but memory of what's been completed.

[![PyPI version](https://badge.fury.io/py/ralphx.svg)](https://badge.fury.io/py/ralphx)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## What's New in v0.4

- **Sidebar step navigation** — Jump directly to any workflow step from the sidebar tree
- **Multi-account with auto-fallback** — Connect multiple Claude accounts, auto-switch on rate limits
- **Usage tracking** — Real-time 5h/7d progress bars with time position markers
- **Event persistence** — Full session history saved to DB, no browser tab required
- **Planning iterations** — Autonomous design doc refinement with streaming
- **Reliable stop button** — Checkpoint-based process tracking survives server hot-reload
- **62 bug fixes + security hardening** — See [CHANGELOG.md](CHANGELOG.md)

---

## The Full Lifecycle

```
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│    Idea      │ ─▶ │ Design Doc   │ ─▶ │ User Stories │ ─▶ │ Implement    │ ─▶ │    Test      │
│              │    │ Ralph Loop   │    │ Ralph Loop   │    │ Ralph Loop   │    │ Ralph Loop   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │                   │                   │
  "Build an app      Web search +         50-200 stories      Code for each       CLI, API, UI
   that does X"      synthesis            with criteria        story               testing
```

**Start anywhere.** Bring your own design doc, or let a Ralph loop research and create one. Jump straight to implementation if you already have stories.

---

## How It Works

Each workflow step is a **Ralph loop** - the viral Claude Code looping pattern:

1. **Fresh context** - Each iteration starts clean, no token bloat
2. **Memory of progress** - Knows what's done, what's next
3. **Recursive iterations** - Run until complete or hit limits
4. **Real-time monitoring** - Watch progress in the dashboard

```
┌─────────────────────────────────────────────────────────────────┐
│  Story Generation Ralph Loop (iteration 12 of 50)               │
│  ─────────────────────────────────────────────────────────────  │
│  ✓ 47 stories generated                                         │
│  ● Currently: Generating API authentication stories...          │
│  ○ Remaining: Payment processing, notifications                 │
└─────────────────────────────────────────────────────────────────┘
```

**Run your way:**
- Run the entire workflow end-to-end until completion
- Run individual Ralph loops one at a time
- Jump back and forth between Ralph loops as needed
- Pause, resume, or restart anytime

---

## Quick Start

**Copy and paste this into Claude Code:**

```
Install RalphX for me. RalphX is a Ralph wrapper on PyPI that manages Ralph loops
for product development. I'm not technical so please handle everything:

1. Check if I have conda/miniconda installed. If not, install miniconda for my OS.
2. Create a Python 3.11 environment called "ralphx" and activate it
3. Install RalphX from PyPI: pip install ralphx
4. Add RalphX as an MCP server using the full path to the ralphx binary in the conda env (use the right command for my OS to find it)
5. Start the RalphX dashboard: ralphx serve
6. Ask me if I want a desktop shortcut to launch the dashboard. If yes, create
   a shortcut for my OS that uses the full path to the Python executable in the
   ralphx conda env (don't use conda activate - point directly to the python binary)

Use the ask question tool if you need any info from me. Don't assume I know
how to run commands - just do everything for me and tell me when it's ready.
```

Claude will handle the entire installation. When done, tell Claude:

> "Register this project and help me build a workflow from my idea for [describe your app]"

Or if you have a design doc:

> "Register this project and create a planning workflow from my README"

Open `http://localhost:16768` to monitor progress.

![Dashboard](https://raw.githubusercontent.com/jackneil/ralphx/main/docs/images/dashboard-overview.png)

---

**Already technical?** Here's the quick setup:

```bash
# Create and activate a Python 3.11+ environment:
conda create -n ralphx python=3.11 -y && conda activate ralphx

# Install RalphX:
pip install ralphx

# Add MCP server with full path to ralphx binary:

# Linux/Mac:
claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- "$(which ralphx)" mcp

# Mac (zsh) - if "which ralphx" fails, first run: conda init zsh && source ~/.zshrc

# Windows - first find your path, then use it:
#   CMD:        where.exe ralphx
#   PowerShell: (Get-Command ralphx).Source
claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- C:\Users\YOU\miniconda3\envs\ralphx\Scripts\ralphx.exe mcp
```

---

## Supported Ralph Loop Types

### Research & Design Ralph Loop
Start from an idea. Claude searches the web, synthesizes findings, and builds out a comprehensive design document.

### Story Generation Ralph Loop
Claude extracts and generates robust user stories from your design document:
- Clear titles and descriptions
- Acceptance criteria
- Priority and categorization

Optionally enable **web-enhanced mode**: Claude uses your design doc as inspiration, then searches the web to discover related requirements and user stories you may have missed.

### Implementation Ralph Loop
Each iteration of the implementation Ralph loop:
1. **Fresh context** - Starts clean with your design doc, guardrails, and progress summary
2. **Knows what's done** - Sees all implemented stories with their git commits (can look back if needed)
3. **Detects duplicates** - Checks if a story is already implemented, marks it dup, moves on
4. **Implements ONE story** - Reads codebase, writes code that fits your patterns, adds tests
5. **Commits** - Creates a git commit after each story, then loops to the next

### Coming Soon: Testing Ralph Loops
- **CLI Testing Ralph Loop** - Run commands, verify output, loop until tests pass
- **Backend Testing Ralph Loop** - API endpoints, database operations
- **UI Testing Ralph Loop** - Chrome/Playwright automation via Claude

---

## The Dashboard

![Workflow Timeline](https://raw.githubusercontent.com/jackneil/ralphx/main/docs/images/workflow-timeline.png)

**Monitor your Ralph loops in real-time:**
- See which Ralph loop is running and iteration progress
- Watch Claude's actual output as it works
- View generated stories and implementations
- Start, pause, or stop Ralph loops anytime

---

## Workflow Templates

Pre-built workflows that chain Ralph loops together:

| Template | Ralph Loops |
|----------|-------------|
| **New Product** | Research → Design Doc → Stories → Implement → Test |
| **From PRD** | Stories → Implement → Test |
| **Feature Add** | Impact Analysis → Tasks → Implement → Test |
| **Bug Fix** | Import Issues → Triage → Root Cause → Fix → Verify |
| **Security Audit** | Scan → Prioritize → Remediate → Verify |

Ask Claude: *"Set up a new-product workflow starting from my idea for a task management app"*

---

## Coming Soon

**More Ralph Loop Types:**
- CLI/backend testing Ralph loops
- Chrome/Playwright UI testing Ralph loops
- Recursive test-fix cycles until green

**Integrations:**
- GitHub Issues - Import bugs and features directly
- Jira - Sync with existing project management
- Sentry - Turn production errors into bugs
- Slack - Notifications when workflows complete

**Triggers:**
- Scheduled workflows (cron-style)
- Webhook triggers from CI/CD
- Git push/PR triggers

**Mobile Access:**
- Mobile-friendly dashboard for monitoring on the go
- Remote access setup instructions in the wiki

---

## Manual Installation

For those who prefer to do it themselves:

```bash
# Create a virtual environment (use conda, venv, or your preferred tool)
# Example with conda:
conda create -n ralphx python=3.11 -y
conda activate ralphx

# Or with venv:
# python3 -m venv ~/.venvs/ralphx && source ~/.venvs/ralphx/bin/activate

# Install RalphX
pip install ralphx

# Set up MCP so Claude can control RalphX (uses full path so it works outside the env)
# Linux/Mac:
claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- "$(which ralphx)" mcp
# Mac (zsh): if "which" fails, run: conda init zsh && source ~/.zshrc
# Windows: find path with "where.exe ralphx" (CMD) or "(Get-Command ralphx).Source" (PowerShell)
#          then: claude mcp add ralphx -e PYTHONDONTWRITEBYTECODE=1 -- C:\Users\YOU\...\ralphx.exe mcp

# Start the dashboard
ralphx serve
# Open http://localhost:16768
```

---

## Multi-Account Management

Connect multiple Claude accounts and assign them per project:
- **Per-project accounts** — Each project can use a different Claude account
- **Usage tracking** — Real-time 5-hour and 7-day usage progress bars per account
- **Auto-fallback** — When one account hits rate limits, automatically retry with another that has capacity
- **Time markers** — Visual indicator showing where you are in each usage window

---

## Why RalphX?

| Problem | RalphX Solution |
|---------|-----------------|
| Ralph loops are powerful but manual | RalphX chains Ralph loops into full workflows |
| Claude Code loses context on long tasks | Fresh context per iteration with memory of progress |
| Hard to track what's done | Real-time dashboard shows exact progress |
| Starting from scratch is overwhelming | Research Ralph loop builds design docs from ideas |
| No visibility into AI work | Watch Claude's actual output as it works |
| Mixed billing across projects | Per-project subscription configuration |

---

## CLI Reference

```bash
ralphx add <path>           # Register a project
ralphx serve                # Start dashboard
ralphx doctor               # Check prerequisites
ralphx why <workflow>       # Explain why something stopped
```

---

## MCP Tools (67 total)

Claude gets full access to RalphX:

| Category | What Claude Can Do |
|----------|-------------------|
| **Projects** | Register, list, configure projects |
| **Workflows** | Create, start, stop, advance steps |
| **Items** | Manage stories, tasks, bugs |
| **Monitoring** | Check progress, view logs |
| **Diagnostics** | Health checks, troubleshooting |

---

## Documentation

- [SDLC Workflows](design/SDLC_WORKFLOWS.md) - All workflow templates explained
- [Design Overview](design/DESIGN.md) - Architecture deep dive
- [Loop Schema](design/LOOP_SCHEMA.md) - Configuration reference
- [Backup & Import Guide](docs/BACKUP_AND_IMPORT.md) - Export workflows, import items

---

## License

MIT
