Ralph Orchestrator

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 | Quick Start | API Reference | 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, 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
• Deployment Guidance: ✅ AVAILABLE (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)

# 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

# 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

  # 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 (formerly Q Chat)

  # Follow installation instructions in repo
  

• Q Chat (Legacy)

  # Follow installation instructions in repo
  

• Gemini CLI

  npm install -g @google/gemini-cli
  

• ACP-Compliant Agents (Agent Client Protocol)

  # 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

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:

# 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

# 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

ralph run
# or with config file
ralph -c ralph.yml

Usage

Basic Commands

# 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

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.

Quick Start with ACP

# 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:

Configuration

Configure ACP in ralph.yml:

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

# 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)

# 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)

echo "Write a Python function to check if a number is prime" > PROMPT.md
ralph run -a claude --max-iterations 5

Web Application

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

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

# 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

# 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

# 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

# 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

# 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

# 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.

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 - Creator of the Ralph Wiggum technique
• Harper Reed - Spec-driven development methodology
• Anthropic, Google, Q - For providing excellent AI CLI tools

Support

• Documentation: Full Documentation
• Deployment Guide: Deployment (alpha)
• Issues: GitHub Issues
• Discussions: GitHub 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