Add Ralph CLI section to README.md

Changes: - Update "What's Included": Add Ralph CLI Integration (Advanced) - Add comprehensive "Ralph CLI Integration" section: * What Ralph CLI does * How it works (background execution) * Key features table * Control modes (agents/always/off) * Monitoring & control commands * Real-life example workflow * Ralph vs PROACTIVELY comparison table * Installation instructions * When to use Ralph CLI - Update "Complete Source Guide": 6 → 7 major open-source projects - Add Ralph CLI as 6th component in source guide Total Ralph mentions: 0 → 37 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 10:11:10 +00:00
parent 99cb591bf7
commit 8fc4565690
1 changed files with 158 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -175,6 +175,7 @@ Follow the step-by-step guide below for full control over each component.
  - **7 PROACTIVELY coordinators** that auto-trigger and orchestrate specialists
  - **31 specialist agents** for domain-specific tasks
 - **🔧 15+ MCP Tools** for vision, search, and GitHub integration
+- **🤖 Ralph CLI Integration** (Advanced) - Autonomous agent looping with background execution
 - **⚡ Intelligent Coordination** - Coordinators automatically detect context and orchestrate workflows
 - **🎛️ Interactive Installation** with model selection (Anthropic/Z.AI)
 - **🛡️ One-Click Setup** with comprehensive verification
@@ -364,6 +365,155 @@ Result: Complete viral app, launch-ready, in 2 weeks ✓

 ---

+## 🤖 Ralph CLI Integration (Advanced)
+
+**🔗 Source:** [@iannuttall/ralph](https://github.com/iannuttall/ralph)
+
+> **⚠️ Advanced Feature:** Ralph CLI provides autonomous agent looping for complex, multi-hour development sessions. It's optional but powerful for "fire and forget" workflows.
+
+### What Ralph CLI Does
+
+**PROACTIVELY Agents** = Quick coordination (single interaction)
+**Ralph CLI** = Autonomous looping (multi-iteration, background execution)
+
+Ralph CLI runs in the **background** (non-blocking), allowing you to continue working in Claude Code while it autonomously completes complex tasks.
+
+### How It Works
+
+```
+1. You request: "Build a TikTok app in 2 weeks"
+      ↓
+2. Hook detects agent request
+      ↓
+3. Hook spawns Ralph in BACKGROUND (non-blocking)
+      ↓
+4. Claude Code immediately continues ← You keep working!
+      ↓
+5. Ralph autonomously loops in background:
+   - Iteration 1: rapid-prototyper builds MVP
+   - Iteration 2: tiktok-strategist plans viral features
+   - Iteration 3: frontend-developer builds UI
+   - Continues until complete or max iterations reached
+      ↓
+6. Monitor Ralph: tail -f ~/.claude/ralph-output.log
+```
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Background Execution** | Runs as background process (NON-BLOCKING) |
+| **Auto-Spawning** | Hook automatically starts Ralph when needed |
+| **Process Tracking** | PID file for monitoring and control |
+| **Lock Mechanism** | Prevents duplicate Ralph instances |
+| **Real-time Logging** | Monitor progress: `tail -f ~/.claude/ralph-output.log` |
+| **Persistent State** | State preserved in `~/.claude/ralph-loop.local.md` |
+
+### Control Modes
+
+```bash
+# Mode 1: Auto-start only for agent requests (default)
+export RALPH_AUTO_MODE="agents"
+
+# Mode 2: Auto-start for everything
+export RALPH_AUTO_MODE="always"
+
+# Mode 3: Disable auto-start
+export RALPH_AUTO_MODE="off"
+
+# Set max iterations (default: 50)
+export RALPH_MAX_ITERATIONS="100"
+```
+
+### Monitoring & Control
+
+```bash
+# Monitor Ralph's output in real-time
+tail -f ~/.claude/ralph-output.log
+
+# Check if Ralph is running
+cat ~/.claude/ralph.pid
+
+# Stop Ralph manually
+kill $(cat ~/.claude/ralph.pid)
+rm ~/.claude/ralph.lock
+
+# View trigger history
+cat ~/.claude/ralph-trigger.log
+```
+
+### Real-Life Example
+
+**Scenario:** You need to build a complex feature while handling other tasks.
+
+```bash
+You: "Use the ai-engineer to implement a machine learning pipeline"
+
+[Hook triggers automatically]
+
+🔄 Ralph CLI auto-started in background
+   PID: 12345
+   Agent: ai-engineer
+   Monitor: tail -f ~/.claude/ralph-output.log
+
+Claude: "I've delegated the ML pipeline to Ralph, which is now
+         working autonomously in the background (20-30 min expected).
+         I'm still available to help with other tasks!"
+
+You: "Perfect. While Ralph works on the ML pipeline, can you help me
+       write unit tests for the authentication module?"
+
+Claude: "Absolutely! Let's write those tests..."
+[You work on tests while Ralph builds the ML pipeline in background]
+```
+
+### Ralph vs PROACTIVELY Agents
+
+| Feature | Ralph CLI (Background) | PROACTIVELY Agents |
+|---------|------------------------|-------------------|
+| **Execution** | Multi-loop, background | Single interaction |
+| **Blocking** | NON-BLOCKING | Blocking (waits) |
+| **State** | File + log | Context only |
+| **Control** | Manual stop (PID) | Automatic completion |
+| **Best For** | Large projects, overnight | Quick tasks, collaboration |
+
+### Installation
+
+Ralph CLI is available as an **optional** installation step in both:
+- **MASTER-PROMPT.md** (Step 6)
+- **interactive-install-claude.sh** (Step 6: Ralph CLI Selection)
+
+**To install:**
+```bash
+npm install -g @iannuttall/ralph
+```
+
+**To enable auto-trigger:**
+```bash
+# The installer creates the hook automatically
+# Or manually: Follow Step 6 in MASTER-PROMPT.md
+```
+
+### When to Use Ralph CLI
+
+✅ **Use Ralph CLI for:**
+- Complex multi-step projects (2+ hours)
+- "Fire and forget" autonomous coding
+- Overnight builds/refactors
+- Large-scale refactoring
+- Multi-feature implementations
+
+❌ **Use PROACTIVELY agents for:**
+- Quick tasks (minutes)
+- Human collaboration needed
+- Design discussions
+- Code reviews
+- Quick fixes
+
+**You can use BOTH together** - Set `RALPH_AUTO_MODE="agents"` for a hybrid approach where Ralph assists with big tasks while PROACTIVELY agents handle quick coordination.
+
+---
+
 ## 🔧 MCP Tools

 ### Vision Tools (8 tools)
@@ -400,11 +550,11 @@ Result: Complete viral app, launch-ready, in 2 weeks ✓

 ## 📖 Complete Source Guide

-This suite integrates **6 major open-source projects**:
+This suite integrates **7 major open-source projects**:

 ### 1. contains-studio/agents 🎭
 **Source:** https://github.com/contains-studio/agents
-**Provides:** 37 specialized agents with PROACTIVELY auto-triggering
+**Provides:** 38 specialized agents with PROACTIVELY auto-triggering
 **Key Innovation:** Context-aware agent selection system

 ### 2. @z_ai/mcp-server 🖼️
@@ -427,7 +577,12 @@ This suite integrates **6 major open-source projects**:
 **Provides:** Professional UI/UX design agent with comprehensive patterns
 **Key Feature:** PROACTIVELY auto-triggering for all design work

-### 6. claude-codex-settings 📋
+### 6. @iannuttall/ralph 🤖
+**Source:** https://github.com/iannuttall/ralph
+**Provides:** Autonomous agent looping with background execution
+**Key Feature:** "Fire and forget" multi-iteration development
+
+### 7. claude-codex-settings 📋
 **Source:** https://github.com/fcakyon/claude-codex-settings
 **Provides:** MCP configuration best practices (reference)
 **Key Feature:** Proven integration patterns