An AI agent orchestration system, Ralph Orchestrator implements the Ralph Wiggum technique to enable agents to iteratively complete tasks. It provides a robust, tested framework for automating AI-driven development workflows, targeting engineers and researchers seeking to streamline complex AI agent interactions.

How It Works

The system operates by continuously running an AI agent against a prompt file, checking for task completion or predefined limits. Key design choices include an async-first architecture for non-blocking I/O, Git-based asynchronous checkpointing for state recovery and history, prompt archiving to track evolution, and robust error handling with exponential backoff. This approach ensures resilience and maintainability in autonomous agent loops.

Quick Start & Requirements

• Installation: Recommended: uv tool install ralph-orchestrator. Pip: pip install ralph-orchestrator. For developers: git clone, then uv sync or pip install -e ..
• Prerequisites: Requires at least one AI CLI tool (e.g., Claude SDK, Kiro CLI, Gemini CLI). Claude SDK necessitates the ANTHROPIC_API_KEY environment variable. Gemini CLI requires npm install -g @google/gemini-cli.
• Documentation: Links to Full Documentation, Quick Start, API Reference, and Examples are available within the README.

Highlighted Details

• Supports multiple AI agents including Claude, Kiro CLI, Q Chat, Gemini CLI, and ACP-compliant agents.
• Full ACP (Agent Client Protocol) integration enables seamless use of ACP-compliant agents with features like file and terminal operations.
• Git-based asynchronous checkpointing allows for recovery and history tracking of agent iterations.
• Features comprehensive testing with over 920 passing tests, ensuring reliability.
• Includes web search capabilities for Claude and robust error recovery mechanisms.

Maintenance & Community

The project is described as a "toy project" undergoing cleanup, indicating active development but without specific details on community channels (e.g., Discord, Slack), notable contributors, or sponsorships provided in the README.

Licensing & Compatibility

Licensed under the MIT License. No specific restrictions for commercial use or closed-source linking are detailed.

Limitations & Caveats

The project is explicitly noted as a "toy project" with potential for bugs, missing functionality, and breaking changes as it is actively being cleaned up.