Fix project isolation: Make loadChatHistory respect active project sessions
- 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>
This commit is contained in:
uroma
@@ -0,0 +1,715 @@
|
||||
Metadata-Version: 2.4
|
||||
Name: ralph-orchestrator
|
||||
Version: 1.2.3
|
||||
Summary: Simple yet powerful AI agent orchestration using the Ralph Wiggum technique
|
||||
Project-URL: Homepage, https://mikeyobrien.github.io/ralph-orchestrator/
|
||||
Project-URL: Repository, https://github.com/mikeyobrien/ralph-orchestrator
|
||||
Project-URL: Documentation, https://mikeyobrien.github.io/ralph-orchestrator/
|
||||
Project-URL: Issues, https://github.com/mikeyobrien/ralph-orchestrator/issues
|
||||
Author-email: Mikey O'Brien <m@mobrienv.dev>
|
||||
License-Expression: MIT
|
||||
License-File: LICENSE
|
||||
Classifier: Development Status :: 4 - Beta
|
||||
Classifier: Intended Audience :: Developers
|
||||
Classifier: License :: OSI Approved :: MIT License
|
||||
Classifier: Operating System :: OS Independent
|
||||
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
|
||||
Classifier: Topic :: System :: Systems Administration
|
||||
Requires-Python: >=3.10
|
||||
Requires-Dist: aiofiles>=24.1.0
|
||||
Requires-Dist: bcrypt<5.0.0,>=4.0.0
|
||||
Requires-Dist: claude-agent-sdk>=0.1.10
|
||||
Requires-Dist: fastapi>=0.116.1
|
||||
Requires-Dist: passlib>=1.7.4
|
||||
Requires-Dist: psutil>=7.0.0
|
||||
Requires-Dist: pyjwt>=2.10.1
|
||||
Requires-Dist: python-multipart>=0.0.20
|
||||
Requires-Dist: pyyaml>=6.0.0
|
||||
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0
|
||||
Requires-Dist: rich>=13.0.0
|
||||
Requires-Dist: sqlalchemy>=2.0.43
|
||||
Requires-Dist: uvicorn[standard]>=0.35.0
|
||||
Requires-Dist: websockets>=15.0.1
|
||||
Provides-Extra: dev
|
||||
Requires-Dist: pytest-asyncio>=1.1.0; extra == 'dev'
|
||||
Requires-Dist: pytest>=8.4.2; extra == 'dev'
|
||||
Requires-Dist: ruff>=0.12.12; extra == 'dev'
|
||||
Requires-Dist: typing-extensions>=4.0.0; extra == 'dev'
|
||||
Provides-Extra: docs
|
||||
Requires-Dist: mkdocs-material-extensions>=1.3.1; extra == 'docs'
|
||||
Requires-Dist: mkdocs-material>=9.6.19; extra == 'docs'
|
||||
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
|
||||
Requires-Dist: pymdown-extensions>=10.16.1; extra == 'docs'
|
||||
Description-Content-Type: text/markdown
|
||||
|
||||
# Ralph Orchestrator
|
||||
|
||||
[](https://mikeyobrien.github.io/ralph-orchestrator/)
|
||||
[](https://github.com/mikeyobrien/ralph-orchestrator/releases)
|
||||
[](LICENSE)
|
||||
[](tests/)
|
||||
[](https://github.com/hesreallyhim/awesome-claude-code)
|
||||
|
||||
A functional, early-stage (alpha) implementation of the Ralph Wiggum software engineering technique — putting AI agents in a loop until the task is done.
|
||||
|
||||
> "Me fail English? That's unpossible!" - Ralph Wiggum
|
||||
|
||||
### NOTE: Ralph is alpha-quality and under active development. It works today, but expect rough edges, occasional bugs, and breaking API/config changes between releases. Primarily tested via the Claude Agent SDK adapter path.
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
**[View Full Documentation](https://mikeyobrien.github.io/ralph-orchestrator/)** | [Quick Start](https://mikeyobrien.github.io/ralph-orchestrator/quick-start/) | [API Reference](https://mikeyobrien.github.io/ralph-orchestrator/api/) | [Examples](https://mikeyobrien.github.io/ralph-orchestrator/examples/)
|
||||
|
||||
## Overview
|
||||
|
||||
Ralph Orchestrator implements a simple but effective pattern for autonomous task completion using AI agents. It continuously runs an AI agent against a prompt file until the task is marked as complete or limits are reached.
|
||||
|
||||
Based on the Ralph Wiggum technique by [Geoffrey Huntley](https://ghuntley.com/ralph/), this implementation provides a robust, tested, and actively developed orchestration system for AI-driven development.
|
||||
|
||||
## 🧪 Alpha Status - v1.2.3
|
||||
|
||||
- **Claude Integration**: ✅ COMPLETE (with Agent SDK)
|
||||
- **Kiro CLI Integration**: ✅ COMPLETE (Successor to Q Chat)
|
||||
- **Q Chat Integration**: ✅ COMPLETE (Legacy Support)
|
||||
- **Gemini Integration**: ✅ COMPLETE
|
||||
- **ACP Protocol Support**: ✅ COMPLETE (Agent Client Protocol)
|
||||
- **Core Orchestration**: ✅ OPERATIONAL
|
||||
- **Test Suite**: ✅ 920+ tests passing
|
||||
- **Documentation**: ✅ [COMPLETE](https://mikeyobrien.github.io/ralph-orchestrator/)
|
||||
- **Deployment Guidance**: ✅ [AVAILABLE](https://mikeyobrien.github.io/ralph-orchestrator/advanced/production-deployment/) (for advanced users; expect changes)
|
||||
|
||||
## Features
|
||||
|
||||
- 🤖 **Multiple AI Agent Support**: Works with Claude, Kiro CLI, Q Chat, Gemini CLI, and ACP-compliant agents
|
||||
- 🔍 **Auto-detection**: Automatically detects which AI agents are available
|
||||
- 🌐 **WebSearch Support**: Claude can search the web for current information
|
||||
- 💾 **Checkpointing**: Git-based async checkpointing for recovery and history
|
||||
- 📚 **Prompt Archiving**: Tracks prompt evolution over iterations
|
||||
- 🔄 **Error Recovery**: Automatic retry with exponential backoff (non-blocking)
|
||||
- 📊 **State Persistence**: Saves metrics and state for analysis
|
||||
- ⏱️ **Configurable Limits**: Set max iterations and runtime limits
|
||||
- 🧪 **Comprehensive Testing**: 620+ tests with unit, integration, and async coverage
|
||||
- 🎨 **Rich Terminal Output**: Beautiful formatted output with syntax highlighting
|
||||
- 🔒 **Security Features**: Automatic masking of API keys et sensitive data in logs
|
||||
- ⚡ **Async-First Design**: Non-blocking I/O throughout (logging, git operations)
|
||||
- 📝 **Inline Prompts**: Run with `-p "your task"` without needing a file
|
||||
- 🧠 **Agent Scratchpad**: All agents persist context across iterations via `.agent/scratchpad.md`
|
||||
|
||||
## Installation
|
||||
|
||||
### For Users (Recommended)
|
||||
|
||||
```bash
|
||||
# Install with uv tool (easiest way to run Ralph globally)
|
||||
uv tool install ralph-orchestrator
|
||||
|
||||
# Or install with pip
|
||||
pip install ralph-orchestrator
|
||||
```
|
||||
|
||||
### For Developers
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/mikeyobrien/ralph-orchestrator.git
|
||||
cd ralph-orchestrator
|
||||
|
||||
# Install with uv (recommended)
|
||||
uv sync
|
||||
|
||||
# Or install with pip (requires pip in virtual environment)
|
||||
python -m pip install -e .
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
At least one AI CLI tool must be installed:
|
||||
|
||||
- **[Claude SDK](https://pypi.org/project/claude-code-sdk/)**
|
||||
```bash
|
||||
# Automatically installed via dependencies
|
||||
# Requires ANTHROPIC_API_KEY environment variable with proper permissions:
|
||||
# - Read/Write access to conversations
|
||||
# - Model access (Claude 3.5 Sonnet or similar)
|
||||
# - Sufficient rate limits for continuous operation
|
||||
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
```
|
||||
|
||||
- **[Kiro CLI](https://github.com/kiro-cli/kiro)** (formerly Q Chat)
|
||||
```bash
|
||||
# Follow installation instructions in repo
|
||||
```
|
||||
|
||||
- **[Q Chat](https://github.com/qchat/qchat)** (Legacy)
|
||||
```bash
|
||||
# Follow installation instructions in repo
|
||||
```
|
||||
|
||||
- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)**
|
||||
```bash
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
- **ACP-Compliant Agents** (Agent Client Protocol)
|
||||
```bash
|
||||
# Any ACP-compliant agent can be used via the ACP adapter
|
||||
# Example: Gemini CLI with ACP mode
|
||||
ralph run -a acp --acp-agent gemini
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Initialize a project
|
||||
```bash
|
||||
ralph init
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `PROMPT.md` - Task description template
|
||||
- `ralph.yml` - Configuration file
|
||||
- `.agent/` - Workspace directories for prompts, checkpoints, metrics, plans, and memory
|
||||
|
||||
### 2. Configure Ralph (optional)
|
||||
Edit `ralph.yml` to customize settings:
|
||||
```yaml
|
||||
# Ralph Orchestrator Configuration
|
||||
agent: auto # Which agent to use: claude, kiro, q, gemini, acp, auto
|
||||
prompt_file: PROMPT.md # Path to prompt file
|
||||
max_iterations: 100 # Maximum iterations before stopping
|
||||
max_runtime: 14400 # Maximum runtime in seconds (4 hours)
|
||||
verbose: false # Enable verbose output
|
||||
|
||||
# Adapter configurations
|
||||
adapters:
|
||||
claude:
|
||||
enabled: true
|
||||
timeout: 300 # Timeout in seconds
|
||||
kiro:
|
||||
enabled: true
|
||||
timeout: 300
|
||||
q:
|
||||
enabled: true
|
||||
timeout: 300
|
||||
gemini:
|
||||
enabled: true
|
||||
timeout: 300
|
||||
acp: # Agent Client Protocol adapter
|
||||
enabled: true
|
||||
timeout: 300
|
||||
tool_permissions:
|
||||
agent_command: gemini # Command to run the ACP agent
|
||||
agent_args: [] # Additional arguments
|
||||
permission_mode: auto_approve # auto_approve, deny_all, allowlist, interactive
|
||||
permission_allowlist: [] # Patterns for allowlist mode
|
||||
```
|
||||
|
||||
### 3. Edit PROMPT.md with your task
|
||||
```markdown
|
||||
# Task: Build a Python Calculator
|
||||
|
||||
Create a calculator module with:
|
||||
- Basic operations (add, subtract, multiply, divide)
|
||||
- Error handling for division by zero
|
||||
- Unit tests for all functions
|
||||
|
||||
<!-- Ralph will continue iterating until limits are reached -->
|
||||
```
|
||||
|
||||
### 4. Run Ralph
|
||||
```bash
|
||||
ralph run
|
||||
# or with config file
|
||||
ralph -c ralph.yml
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Commands
|
||||
|
||||
```bash
|
||||
# Run with auto-detected agent
|
||||
ralph
|
||||
|
||||
# Use configuration file
|
||||
ralph -c ralph.yml
|
||||
|
||||
# Use specific agent
|
||||
ralph run -a claude
|
||||
ralph run -a kiro
|
||||
ralph run -a q
|
||||
ralph run -a gemini
|
||||
ralph run -a acp # ACP-compliant agent
|
||||
|
||||
# Check status
|
||||
ralph status
|
||||
|
||||
# Clean workspace
|
||||
ralph clean
|
||||
|
||||
# Dry run (test without executing)
|
||||
ralph run --dry-run
|
||||
```
|
||||
|
||||
### Advanced Options
|
||||
|
||||
```bash
|
||||
ralph [OPTIONS] [COMMAND]
|
||||
|
||||
Commands:
|
||||
init Initialize a new Ralph project
|
||||
status Show current Ralph status
|
||||
clean Clean up agent workspace
|
||||
prompt Generate structured prompt from rough ideas
|
||||
run Run the orchestrator (default)
|
||||
|
||||
Core Options:
|
||||
-c, --config CONFIG Configuration file (YAML format)
|
||||
-a, --agent {claude,kiro,q,gemini,acp,auto} AI agent to use (default: auto)
|
||||
-P, --prompt-file FILE Prompt file path (default: PROMPT.md)
|
||||
-p, --prompt-text TEXT Inline prompt text (overrides file)
|
||||
--completion-promise TEXT Stop when agent output contains this exact string (default: LOOP_COMPLETE)
|
||||
-i, --max-iterations N Maximum iterations (default: 100)
|
||||
-t, --max-runtime SECONDS Maximum runtime (default: 14400)
|
||||
-v, --verbose Enable verbose output
|
||||
-d, --dry-run Test mode without executing agents
|
||||
|
||||
ACP Options:
|
||||
--acp-agent COMMAND ACP agent command (default: gemini)
|
||||
--acp-permission-mode MODE Permission handling: auto_approve, deny_all, allowlist, interactive
|
||||
|
||||
Advanced Options:
|
||||
--max-tokens MAX_TOKENS Maximum total tokens (default: 1000000)
|
||||
--max-cost MAX_COST Maximum cost in USD (default: 50.0)
|
||||
--checkpoint-interval N Git checkpoint interval (default: 5)
|
||||
--retry-delay SECONDS Retry delay on errors (default: 2)
|
||||
--no-git Disable git checkpointing
|
||||
--no-archive Disable prompt archiving
|
||||
--no-metrics Disable metrics collection
|
||||
```
|
||||
|
||||
## ACP (Agent Client Protocol) Integration
|
||||
|
||||
Ralph supports any ACP-compliant agent through its ACP adapter. This enables integration with agents like Gemini CLI that implement the [Agent Client Protocol](https://github.com/anthropics/agent-client-protocol).
|
||||
|
||||
### Quick Start with ACP
|
||||
|
||||
```bash
|
||||
# Basic usage with Gemini CLI
|
||||
ralph run -a acp --acp-agent gemini
|
||||
|
||||
# With permission mode
|
||||
ralph run -a acp --acp-agent gemini --acp-permission-mode auto_approve
|
||||
```
|
||||
|
||||
### Permission Modes
|
||||
|
||||
The ACP adapter supports four permission modes for handling agent tool requests:
|
||||
|
||||
| Mode | Description | Use Case |
|
||||
|------|-------------|----------|
|
||||
| `auto_approve` | Approve all requests automatically | Trusted environments, CI/CD |
|
||||
| `deny_all` | Deny all permission requests | Testing, sandboxed execution |
|
||||
| `allowlist` | Only approve matching patterns | Production with specific tools |
|
||||
| `interactive` | Prompt user for each request | Development, manual oversight |
|
||||
|
||||
### Configuration
|
||||
|
||||
Configure ACP in `ralph.yml`:
|
||||
|
||||
```yaml
|
||||
adapters:
|
||||
acp:
|
||||
enabled: true
|
||||
timeout: 300
|
||||
tool_permissions:
|
||||
agent_command: gemini # Agent CLI command
|
||||
agent_args: [] # Additional CLI arguments
|
||||
permission_mode: auto_approve
|
||||
permission_allowlist: # For allowlist mode
|
||||
- "fs/read_text_file:*.py"
|
||||
- "fs/write_text_file:src/*"
|
||||
- "terminal/create:pytest*"
|
||||
```
|
||||
|
||||
### Agent Scratchpad
|
||||
|
||||
All agents maintain context across iterations via `.agent/scratchpad.md`. This file persists:
|
||||
- Progress from previous iterations
|
||||
- Decisions and context
|
||||
- Current blockers or issues
|
||||
- Remaining work items
|
||||
|
||||
The scratchpad enables agents to continue from where they left off rather than restarting each iteration.
|
||||
|
||||
### Supported Operations
|
||||
|
||||
The ACP adapter handles these agent requests:
|
||||
|
||||
**File Operations:**
|
||||
- `fs/read_text_file` - Read file contents (with path security validation)
|
||||
- `fs/write_text_file` - Write file contents (with path security validation)
|
||||
|
||||
**Terminal Operations:**
|
||||
- `terminal/create` - Create subprocess with command
|
||||
- `terminal/output` - Read process output
|
||||
- `terminal/wait_for_exit` - Wait for process completion
|
||||
- `terminal/kill` - Terminate process
|
||||
- `terminal/release` - Release terminal resources
|
||||
|
||||
## How It Works
|
||||
|
||||
### The Ralph Loop
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Read PROMPT.md │
|
||||
└────────┬────────┘
|
||||
│
|
||||
v
|
||||
┌─────────────────┐
|
||||
│ Execute AI Agent│<──────┐
|
||||
└────────┬────────┘ │
|
||||
│ │
|
||||
v │
|
||||
┌─────────────────┐ │
|
||||
│ Check Complete? │───No──┘
|
||||
└────────┬────────┘
|
||||
│Yes
|
||||
v
|
||||
┌─────────────────┐
|
||||
│ Done! │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Execution Flow
|
||||
|
||||
1. **Initialization**: Creates `.agent/` directories and validates prompt file
|
||||
2. **Agent Detection**: Auto-detects available AI agents (claude, kiro, q, gemini)
|
||||
3. **Iteration Loop**:
|
||||
- Executes AI agent with current prompt
|
||||
- Monitors for task completion marker
|
||||
- Creates checkpoints at intervals
|
||||
- Handles errors with retry logic
|
||||
4. **Completion**: Stops when:
|
||||
- Max iterations reached
|
||||
- Max runtime exceeded
|
||||
- Cost limits reached
|
||||
- Too many consecutive errors
|
||||
- Completion promise matched (default: LOOP_COMPLETE)
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
ralph-orchestrator/
|
||||
├── src/
|
||||
│ └── ralph_orchestrator/
|
||||
│ ├── __main__.py # CLI entry point
|
||||
│ ├── main.py # Configuration and types
|
||||
│ ├── orchestrator.py # Core orchestration logic (async)
|
||||
│ ├── adapters/ # AI agent adapters
|
||||
│ │ ├── base.py # Base adapter interface
|
||||
│ │ ├── claude.py # Claude Agent SDK adapter
|
||||
│ │ ├── kiro.py # Kiro CLI adapter
|
||||
│ │ ├── gemini.py # Gemini CLI adapter
|
||||
│ │ ├── qchat.py # Q Chat adapter
|
||||
│ │ ├── acp.py # ACP (Agent Client Protocol) adapter
|
||||
│ │ ├── acp_protocol.py # JSON-RPC 2.0 protocol handling
|
||||
│ │ ├── acp_client.py # Subprocess manager
|
||||
│ │ ├── acp_models.py # Data models
|
||||
│ │ └── acp_handlers.py # Permission/file/terminal handlers
|
||||
│ ├── output/ # Output formatting (NEW)
|
||||
│ │ ├── base.py # Base formatter interface
|
||||
│ │ ├── console.py # Rich console output
|
||||
│ │ ├── rich_formatter.py # Rich text formatting
|
||||
│ │ └── plain.py # Plain text fallback
|
||||
│ ├── async_logger.py # Thread-safe async logging
|
||||
│ ├── context.py # Context management
|
||||
│ ├── logging_config.py # Centralized logging setup
|
||||
│ ├── metrics.py # Metrics tracking
|
||||
│ ├── security.py # Security validation & masking
|
||||
│ └── safety.py # Safety checks
|
||||
├── tests/ # Test suite (620+ tests)
|
||||
│ ├── test_orchestrator.py
|
||||
│ ├── test_adapters.py
|
||||
│ ├── test_async_logger.py
|
||||
│ ├── test_output_formatters.py
|
||||
│ ├── test_config.py
|
||||
│ ├── test_integration.py
|
||||
│ └── test_acp_*.py # ACP adapter tests (305+ tests)
|
||||
├── docs/ # Documentation
|
||||
├── PROMPT.md # Task description (user created)
|
||||
├── ralph.yml # Configuration file (created by init)
|
||||
├── pyproject.toml # Project configuration
|
||||
├── .agent/ # CLI workspace (created by init)
|
||||
│ ├── prompts/ # Prompt workspace
|
||||
│ ├── checkpoints/ # Checkpoint markers
|
||||
│ ├── metrics/ # Metrics data
|
||||
│ ├── plans/ # Planning documents
|
||||
│ └── memory/ # Agent memory
|
||||
├── .ralph/ # Runtime metrics directory
|
||||
└── prompts/ # Prompt archive directory
|
||||
└── archive/ # Archived prompt history
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Run Test Suite
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
uv run pytest -v
|
||||
|
||||
# With coverage
|
||||
uv run pytest --cov=ralph_orchestrator
|
||||
|
||||
# Specific test file
|
||||
uv run pytest tests/test_orchestrator.py -v
|
||||
|
||||
# Integration tests only
|
||||
uv run pytest tests/test_integration.py -v
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
|
||||
- ✅ Unit tests for all core functions
|
||||
- ✅ Integration tests with mocked agents
|
||||
- ✅ CLI interface tests
|
||||
- ✅ Error handling and recovery tests
|
||||
- ✅ State persistence tests
|
||||
|
||||
## Examples
|
||||
|
||||
### Inline Prompt (Quick Tasks)
|
||||
|
||||
```bash
|
||||
# Run directly with inline prompt - no file needed
|
||||
ralph run -p "Write a Python function to check if a number is prime" -a claude --max-iterations 5
|
||||
```
|
||||
|
||||
### Simple Function (File-Based)
|
||||
|
||||
```bash
|
||||
echo "Write a Python function to check if a number is prime" > PROMPT.md
|
||||
ralph run -a claude --max-iterations 5
|
||||
```
|
||||
|
||||
### Web Application
|
||||
|
||||
```bash
|
||||
cat > PROMPT.md << 'EOF'
|
||||
Build a Flask web app with:
|
||||
- User registration and login
|
||||
- SQLite database
|
||||
- Basic CRUD operations
|
||||
- Bootstrap UI
|
||||
EOF
|
||||
|
||||
ralph run --max-iterations 50
|
||||
```
|
||||
|
||||
### Test-Driven Development
|
||||
|
||||
```bash
|
||||
cat > PROMPT.md << 'EOF'
|
||||
Implement a linked list in Python using TDD:
|
||||
1. Write tests first
|
||||
2. Implement methods to pass tests
|
||||
3. Add insert, delete, search operations
|
||||
4. Ensure 100% test coverage
|
||||
EOF
|
||||
|
||||
ralph run -a q --verbose
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Check Status
|
||||
```bash
|
||||
# One-time status check
|
||||
ralph status
|
||||
|
||||
# Example output:
|
||||
Ralph Orchestrator Status
|
||||
=========================
|
||||
Prompt: PROMPT.md exists
|
||||
Status: IN PROGRESS
|
||||
Latest metrics: .ralph/metrics_20250907_154435.json
|
||||
{
|
||||
"iteration_count": 15,
|
||||
"runtime": 234.5,
|
||||
"errors": 0
|
||||
}
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# If using verbose mode
|
||||
ralph run --verbose 2>&1 | tee ralph.log
|
||||
|
||||
# Check git history
|
||||
git log --oneline | grep "Ralph checkpoint"
|
||||
```
|
||||
|
||||
## Error Recovery
|
||||
|
||||
Ralph handles errors gracefully:
|
||||
|
||||
- **Retry Logic**: Failed iterations retry after configurable delay
|
||||
- **Error Limits**: Stops after 5 consecutive errors
|
||||
- **Timeout Protection**: 5-minute timeout per iteration
|
||||
- **State Persistence**: Can analyze failures from saved state
|
||||
- **Git Recovery**: Can reset to last working checkpoint
|
||||
|
||||
### Manual Recovery
|
||||
|
||||
```bash
|
||||
# Check last error
|
||||
cat .ralph/metrics_*.json | jq '.errors[-1]'
|
||||
|
||||
# Reset to last checkpoint
|
||||
git reset --hard HEAD
|
||||
|
||||
# Clean and restart
|
||||
ralph clean
|
||||
ralph run
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear Task Definition**: Write specific, measurable requirements
|
||||
2. **Incremental Goals**: Break complex tasks into smaller steps
|
||||
3. **Success Markers**: Define clear completion criteria
|
||||
4. **Regular Checkpoints**: Use default 5-iteration checkpoints
|
||||
5. **Monitor Progress**: Use `ralph status` to track iterations
|
||||
6. **Version Control**: Commit PROMPT.md before starting
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Agent Not Found
|
||||
```bash
|
||||
# For Claude, ensure API key is set with proper permissions
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
# Verify Claude API key permissions:
|
||||
# - Should have access to Claude 3.5 Sonnet or similar model
|
||||
# - Need sufficient rate limits (at least 40,000 tokens/minute)
|
||||
# - Requires read/write access to the API
|
||||
|
||||
# For Q and Gemini, check CLI tools are installed
|
||||
which kiro-cli
|
||||
which q
|
||||
which gemini
|
||||
|
||||
# Install missing CLI tools as needed
|
||||
```
|
||||
|
||||
### Task Not Completing
|
||||
```bash
|
||||
# Check iteration count and progress
|
||||
ralph status
|
||||
|
||||
# Review agent errors
|
||||
cat .agent/metrics/state_*.json | jq '.errors'
|
||||
|
||||
# Try different agent
|
||||
ralph run -a gemini
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
```bash
|
||||
# Reduce iteration timeout
|
||||
ralph run --max-runtime 1800
|
||||
|
||||
# Increase checkpoint frequency
|
||||
ralph run --checkpoint-interval 3
|
||||
```
|
||||
|
||||
## Research & Theory
|
||||
|
||||
The Ralph Wiggum technique is based on several key principles:
|
||||
|
||||
1. **Simplicity Over Complexity**: Keep orchestration minimal (~400 lines)
|
||||
2. **Deterministic Failure**: Fail predictably in an unpredictable world
|
||||
3. **Context Recovery**: Use git and state files for persistence
|
||||
4. **Human-in-the-Loop**: Allow manual intervention when needed
|
||||
|
||||
For detailed research and theoretical foundations, see the [research directory](../README.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Please:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Write tests for new functionality
|
||||
4. Ensure all tests pass (`uv run pytest`)
|
||||
5. Commit changes (`git commit -m 'Add amazing feature'`)
|
||||
6. Push to branch (`git push origin feature/amazing-feature`)
|
||||
7. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See LICENSE file for details
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- **[Geoffrey Huntley](https://ghuntley.com/ralph/)** - Creator of the Ralph Wiggum technique
|
||||
- **[Harper Reed](https://harper.blog/)** - Spec-driven development methodology
|
||||
- **Anthropic, Google, Q** - For providing excellent AI CLI tools
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation**: [Full Documentation](https://mikeyobrien.github.io/ralph-orchestrator/)
|
||||
- **Deployment Guide**: [Deployment (alpha)](https://mikeyobrien.github.io/ralph-orchestrator/advanced/production-deployment/)
|
||||
- **Issues**: [GitHub Issues](https://github.com/mikeyobrien/ralph-orchestrator/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/mikeyobrien/ralph-orchestrator/discussions)
|
||||
- **Research**: [Ralph Wiggum Research](../)
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.2.3** (2026-01-12)
|
||||
- Maintenance release: version metadata and documentation refresh
|
||||
|
||||
- **v1.2.2** (2026-01-08)
|
||||
- **ACP (Agent Client Protocol) Support**: Full integration with ACP-compliant agents
|
||||
- JSON-RPC 2.0 message protocol
|
||||
- Permission handling (auto_approve, deny_all, allowlist, interactive)
|
||||
- File operations (read/write with security)
|
||||
- Terminal operations (create, output, wait, kill, release)
|
||||
- Session management and streaming updates
|
||||
- Agent scratchpad mechanism for context persistence across iterations
|
||||
- New CLI options: `--acp-agent`, `--acp-permission-mode`
|
||||
- Configuration support in ralph.yml
|
||||
- 305+ new ACP-specific tests
|
||||
- Expanded test suite (920+ tests)
|
||||
|
||||
- **v1.1.0** (2025-12)
|
||||
- Async-first architecture for non-blocking operations
|
||||
- Thread-safe async logging with rotation and security masking
|
||||
- Rich terminal output with syntax highlighting
|
||||
- Inline prompt support (`-p "your task"`)
|
||||
- Claude Agent SDK integration with MCP server support
|
||||
- Async git checkpointing (non-blocking)
|
||||
- Expanded test suite (620+ tests)
|
||||
- Improved error handling with debug logging
|
||||
|
||||
- **v1.0.0** (2025-09-07)
|
||||
- Initial release with Claude, Q, and Gemini support
|
||||
- Comprehensive test suite (17 tests)
|
||||
- Robust error handling
|
||||
- Full documentation
|
||||
- Git-based checkpointing
|
||||
- State persistence and metrics
|
||||
|
||||
---
|
||||
|
||||
*"I'm learnding!" - Ralph Wiggum*
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/#mikeyobrien/ralph-orchestrator&type=date&legend=top-left)
|
||||
Reference in New Issue
Block a user