55aafbae9a
- Modified loadChatHistory() to check for active project before fetching all sessions - When active project exists, use project.sessions instead of fetching from API - Added detailed console logging to debug session filtering - This prevents ALL sessions from appearing in every project's sidebar Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
301 lines
9.9 KiB
Markdown
301 lines
9.9 KiB
Markdown
# RalphLoop "Tackle Until Solved" Integration Summary
|
|
|
|
**Date:** 2025-01-22
|
|
**Status:** ✅ Complete
|
|
|
|
## Overview
|
|
|
|
Ralph Orchestrator has been successfully integrated into the Claude Code CLI with the name **"RalphLoop: Tackle Until Solved"**. The integration provides autonomous agent loop functionality that continues iterating until a task is complete.
|
|
|
|
## What Was Built
|
|
|
|
### 1. RalphLoop Wrapper Script
|
|
|
|
**Location:** `/home/uroma/obsidian-web-interface/bin/ralphloop`
|
|
|
|
A Python wrapper script that:
|
|
- Integrates Ralph Orchestrator with Claude Code CLI
|
|
- Creates Ralph projects (PROMPT.md, ralph.yml)
|
|
- Runs autonomous agent loops until completion
|
|
- Supports task descriptions, file input, and configuration options
|
|
|
|
**Usage:**
|
|
```bash
|
|
./ralphloop "Your task description here"
|
|
./ralphloop -i task.md
|
|
./ralphloop --agent claude --max-iterations 50
|
|
```
|
|
|
|
**Environment Variables:**
|
|
- `ANTHROPIC_API_KEY` - Required for Claude agent
|
|
- `RALPH_AGENT` - Override agent selection (claude, gemini, etc.)
|
|
- `RALPH_MAX_ITERATIONS` - Max iterations (default: 100)
|
|
- `RALPH_MAX_RUNTIME` - Max runtime in seconds (default: 14400)
|
|
|
|
### 2. Brainstorming Skill Integration
|
|
|
|
**Location:** `/home/uroma/.claude/skills/brainstorming/`
|
|
|
|
**Files:**
|
|
- `SKILL.md` - Updated with Ralph integration instructions
|
|
- `ralph-integration.py` - Python module for complexity detection and Ralph delegation
|
|
|
|
**Features:**
|
|
- Automatic complexity analysis (threshold: 5 steps)
|
|
- Keyword detection for architecture/system-level tasks
|
|
- Delegates complex tasks to Ralph for autonomous iteration
|
|
- Presents Ralph's validated design as final output
|
|
|
|
**Complexity Triggers:**
|
|
- Architecture keywords: architecture, platform, framework, multi-tenant, distributed
|
|
- Multiple implementation phases
|
|
- Keywords: complex, complete, production, end-to-end
|
|
- User opt-in via environment variables
|
|
|
|
### 3. Agent Pipeline Builder Integration
|
|
|
|
**Location:** `/home/uroma/.claude/skills/agent-pipeline-builder/`
|
|
|
|
**Files:**
|
|
- `SKILL.md` - Updated with Ralph integration instructions
|
|
- `ralph-pipeline.py` - Python module for pipeline complexity detection and Ralph delegation
|
|
|
|
**Features:**
|
|
- Automatic pipeline complexity analysis (threshold: 3 stages or 5/10 complexity)
|
|
- Generates pipeline manifests for Ralph
|
|
- Ralph autonomously builds agent definitions and orchestration scripts
|
|
- Tests each stage and validates end-to-end pipeline
|
|
|
|
## Installation
|
|
|
|
**Ralph Orchestrator installed at:**
|
|
```
|
|
/home/uroma/obsidian-web-interface/.venv/bin/ralph
|
|
```
|
|
|
|
**Installation command used:**
|
|
```bash
|
|
.venv/bin/pip install ralph-orchestrator
|
|
```
|
|
|
|
**Dependencies installed:**
|
|
- ralph-orchestrator-1.2.3
|
|
- claude-agent-sdk-0.1.21
|
|
- fastapi-0.128.0
|
|
- +40 other dependencies
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Claude Code CLI │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Brainstorming / Pipeline Builder │
|
|
│ (Complexity Detection Layer) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌─────────────┴─────────────┐
|
|
│ │
|
|
▼ ▼
|
|
Simple Task Complex Task
|
|
│ │
|
|
▼ ▼
|
|
Direct Mode RalphLoop Wrapper
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ Ralph Orchestrator
|
|
│ (Autonomous
|
|
│ Iteration) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Example 1: Simple Task (Direct Mode)
|
|
|
|
```bash
|
|
/brainstorming "Add a dark mode toggle"
|
|
# Complexity: 1 step → Runs directly, returns in < 2 minutes
|
|
```
|
|
|
|
### Example 2: Complex Task (Ralph Mode)
|
|
|
|
```bash
|
|
/brainstorming "Build a multi-tenant SaaS platform with authentication, billing, and real-time notifications"
|
|
# Complexity: 16 steps → Delegates to Ralph
|
|
```
|
|
|
|
**Output:**
|
|
```
|
|
🔄 Delegating to RalphLoop 'Tackle Until Solved' for autonomous iteration...
|
|
Complexity: 16 steps estimated
|
|
✅ Ralph task initialized: .ralph/PROMPT.md
|
|
Command: /home/uroma/obsidian-web-interface/bin/ralphloop "Build a..."
|
|
...
|
|
✅ Ralph completed in 47 iterations
|
|
```
|
|
|
|
### Example 3: Pipeline with Ralph
|
|
|
|
```bash
|
|
/agent-pipeline-builder "Create a research→analysis→writing pipeline for AI news"
|
|
# Complexity: 6/10 → Delegates to Ralph
|
|
```
|
|
|
|
**Ralph autonomously:**
|
|
1. Creates agent definitions for each stage
|
|
2. Implements orchestration script
|
|
3. Tests each stage independently
|
|
4. Validates end-to-end pipeline
|
|
5. Returns complete, tested pipeline
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
```bash
|
|
# Force Ralph mode for all tasks
|
|
export RALPH_AUTO=true
|
|
|
|
# Force Ralph for brainstorming only
|
|
export BRAINSTORMING_USE_RALPH=true
|
|
|
|
# Force Ralph for pipelines only
|
|
export PIPELINE_USE_RALPH=true
|
|
|
|
# Set max iterations
|
|
export RALPH_MAX_ITERATIONS=50
|
|
|
|
# Set max runtime (4 hours)
|
|
export RALPH_MAX_RUNTIME=14400
|
|
|
|
# Choose agent
|
|
export RALPH_AGENT=claude
|
|
```
|
|
|
|
### Manual Ralph Invocation
|
|
|
|
```bash
|
|
# Direct wrapper usage
|
|
/home/uroma/obsidian-web-interface/bin/ralphloop "Your task"
|
|
|
|
# With file input
|
|
/home/uroma/obsidian-web-interface/bin/ralphloop -i task.md
|
|
|
|
# With custom settings
|
|
/home/uroma/obsidian-web-interface/bin/ralphloop \
|
|
--agent claude \
|
|
--max-iterations 50 \
|
|
"Your task"
|
|
```
|
|
|
|
## Files Created
|
|
|
|
### Ralph Working Directory
|
|
```
|
|
.ralph/
|
|
├── PROMPT.md # Task prompt with success criteria
|
|
├── ralph.yml # Configuration file
|
|
├── state.json # Progress tracking
|
|
└── iterations/
|
|
├── 001.md # First iteration output
|
|
├── 002.md # Second iteration output
|
|
└── final.md # Final validated output
|
|
```
|
|
|
|
### Integration Files
|
|
```
|
|
/home/uroma/obsidian-web-interface/
|
|
├── bin/
|
|
│ └── ralphloop # Wrapper script
|
|
└── .venv/
|
|
└── bin/
|
|
└── ralph # Ralph binary
|
|
|
|
/home/uroma/.claude/skills/
|
|
├── brainstorming/
|
|
│ ├── SKILL.md # Updated with Ralph docs
|
|
│ └── ralph-integration.py # Complexity detection & delegation
|
|
└── agent-pipeline-builder/
|
|
├── SKILL.md # Updated with Ralph docs
|
|
└── ralph-pipeline.py # Pipeline complexity & delegation
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Test Complexity Detection
|
|
|
|
```bash
|
|
# Simple task (no Ralph)
|
|
python3 /home/uroma/.claude/skills/brainstorming/ralph-integration.py \
|
|
"Add a dark mode toggle" --test-complexity
|
|
# Output: Complexity: 1 steps, Should use Ralph: False
|
|
|
|
# Complex task (use Ralph)
|
|
python3 /home/uroma/.claude/skills/brainstorming/ralph-integration.py \
|
|
"Build a multi-tenant SaaS platform" --test-complexity
|
|
# Output: Complexity: 16 steps, Should use Ralph: True
|
|
|
|
# Pipeline complexity
|
|
python3 /home/uroma/.claude/skills/agent-pipeline-builder/ralph-pipeline.py \
|
|
--test-complexity
|
|
# Output: Pipeline complexity: 6/10, Should use Ralph: True
|
|
```
|
|
|
|
## Success Criteria
|
|
|
|
✅ Ralph Orchestrator installed in project venv
|
|
✅ RalphLoop wrapper script created and tested
|
|
✅ Brainstorming skill integrated with Ralph
|
|
✅ Agent-pipeline-builder skill integrated with Ralph
|
|
✅ Complexity detection working correctly
|
|
✅ Environment variable configuration supported
|
|
✅ Documentation complete
|
|
|
|
## Next Steps (Optional Enhancements)
|
|
|
|
1. **Web UI Integration** - Add Ralph progress monitoring to the web interface
|
|
2. **Checkpoint/Resume** - Implement state persistence for interrupted Ralph runs
|
|
3. **Multi-Agent Coordination** - Enable Ralph to coordinate multiple agents in parallel
|
|
4. **Metrics Dashboard** - Track Ralph performance and iteration patterns
|
|
5. **Custom Prompts** - Allow users to provide custom Ralph templates
|
|
|
|
## Troubleshooting
|
|
|
|
### Ralph not found
|
|
```bash
|
|
# Check installation
|
|
ls -la /home/uroma/obsidian-web-interface/.venv/bin/ralph
|
|
|
|
# Reinstall if needed
|
|
/home/uroma/obsidian-web-interface/.venv/bin/pip install ralph-orchestrator
|
|
```
|
|
|
|
### Complexity detection too aggressive
|
|
```bash
|
|
# Adjust threshold in ralph-integration.py
|
|
COMPLEXITY_THRESHOLD = 10 # Increase from 5
|
|
```
|
|
|
|
### Force direct mode
|
|
```bash
|
|
# Disable Ralph for current session
|
|
export RALPH_AUTO=false
|
|
```
|
|
|
|
## References
|
|
|
|
- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
|
|
- Claude Agent SDK: https://github.com/anthropics/claude-agent-sdk
|
|
- Brainstorming Skill: `/home/uroma/.claude/skills/brainstorming/SKILL.md`
|
|
- Pipeline Builder Skill: `/home/uroma/.claude/skills/agent-pipeline-builder/SKILL.md`
|
|
|
|
---
|
|
|
|
**Integration completed:** 2025-01-22
|
|
**Integration by:** Claude Code CLI with brainstorming & agent-pipeline-builder skills
|