|
|
|
|
@@ -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)
|
uroma