ralphx 0.4.3

Autonomous AI loop orchestration for Claude Code - define workflows in YAML, run autonomously, monitor in real-time

RalphX

From idea to working, tested code. Autonomously.

RalphX is a Ralph wrapper for managing Ralph loops across your entire product development lifecycle. Ralph 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.

---

What's New in v0.4.2

• 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 429 rate limits with drag-to-reorder priority and per-project account assignment
• 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
• Multi-account unified UX — Streamlined account management with re-auth scope fixes
• 62 bug fixes + security hardening — See 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:8765 to monitor progress.

---

Already technical? Here's the quick setup:

# Create and activate a Python 3.10+ environment (3.11 recommended):
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

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 Step Types

Each workflow is built by combining steps. Each step uses one of these processing types:

Step Type	What It Does
Design Doc	Interactive planning chat with web research to build a comprehensive design document
Extract Requirements	Extract user stories from your design doc (turbo mode for speed, deep mode for web-enhanced thoroughness)
Web-Gen Requirements	Discover requirements you missed by researching domain best practices on the web
Implementation	Implement user stories one at a time with code changes, tests, and git commits

Build any workflow by combining these steps. For example, a full product workflow would be: Design Doc → Extract Requirements → Implementation.

Ask Claude: "Create a workflow for my project 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

---

Multi-Account Management

Connect multiple Claude accounts and assign them per project:

• Per-project accounts — Each project can use a different Claude account
• Priority ordering — Drag-to-reorder accounts to set fallback priority
• Auto-fallback on 429 — When one account hits rate limits (HTTP 429), automatically retry with the next account that has capacity
• Usage tracking — Real-time 5-hour and 7-day usage progress bars per account
• 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

Core Commands:

ralphx add <path>                          # Register a project
ralphx remove <slug>                       # Unregister a project
ralphx serve                               # Start dashboard (default port 8765)
ralphx run <loop> --project <slug>         # Run a loop from the CLI
ralphx doctor                              # Check system prerequisites
ralphx diagnose --project <slug>           # Run project-specific diagnostics
ralphx why --project <slug>                # Explain why the last run stopped
ralphx validate <loop.yaml>                # Validate a loop configuration file
ralphx mcp                                 # Start MCP server for Claude Code

Project Management:

ralphx projects list                       # List all registered projects
ralphx projects show <slug>                # Show project details and stats

Loop Management:

ralphx loops list --project <slug>         # List all loops for a project
ralphx loops show <name> --project <slug>  # Show loop config details
ralphx loops sync --project <slug>         # Sync loop configs from files to DB

Guardrails:

ralphx guardrails list --project <slug>              # List all guardrail files
ralphx guardrails validate --project <slug>          # Validate guardrail config
ralphx guardrails preview <loop> --project <slug>    # Preview assembled guardrails
ralphx guardrails detect --project <slug>            # Detect AI instruction files
ralphx guardrails templates                          # List guardrail templates

Permissions:

ralphx permissions check --project <slug>                     # Check current permissions
ralphx permissions setup --project <slug> --loop <name>       # Auto-configure for a loop
ralphx permissions preset --project <slug> --preset <name>    # Apply preset (research/implementation/full)

Import:

ralphx import markdown <file> --project <slug> --loop <name>  # Import markdown file
ralphx import jsonl <file> --project <slug> --loop <name>     # Import JSONL work items
ralphx import paste --project <slug> --loop <name> -f <name>  # Import from stdin
ralphx import list --project <slug> --loop <name>             # List input files

---

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 - All workflow templates explained
• Design Overview - Architecture deep dive
• Loop Schema - Configuration reference
• Backup & Import Guide - Export workflows, import items

---

License

MIT