diff --git a/README.md b/README.md index 8bc7f9b..4339dcd 100644 --- 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