Autonomous AI development loop for Claude Code with intelligent exit detection and rate limiting. Ralph enables continuous, iterative project improvement by AI, targeting developers and researchers seeking to automate coding tasks. It offers built-in safeguards against infinite loops and API overuse, streamlining AI-assisted software development.

How It Works

Ralph orchestrates an autonomous development loop using Claude Code. It reads project instructions from PROMPT.md and a prioritized task list from @fix_plan.md, then iteratively executes Claude Code. Intelligent exit detection stops the loop upon task completion, multiple "done" signals, or strong completion indicators. Safeguards include configurable rate limiting (100 calls/hour) and an advanced circuit breaker with multi-line error matching and two-stage filtering to prevent API overuse and stuck loops.

Quick Start & Requirements

• Installation: One-time global installation via ./install.sh. Per-project setup using ralph-setup <project-name> or ralph-import <spec-file> <project-name>.
• Prerequisites: Bash 4.0+, Claude Code CLI (npm install -g @anthropic-ai/claude-code), tmux (for monitoring), jq, Git.
• Project Status: v0.9.0 - Active Development. Test Coverage: ~60% (target 90%+).
• Links: GitHub Repository, Full Roadmap

Highlighted Details

• Autonomous development loops with intelligent exit detection mechanisms.
• Rate limiting (default 100 calls/hour, configurable) and circuit breaker with advanced error detection.
• Functionality to import existing PRDs/specifications (Markdown, text, JSON, DOCX, PDF) into actionable project formats.
• Integrated tmux monitoring for real-time dashboard visualization of loop status and progress.
• Comprehensive test suite with 97 passing tests, covering critical paths and error detection.

Maintenance & Community

The project is under active development (v0.9.0) with a clear roadmap towards v1.0.0, estimated within ~4 weeks. Contributions are actively welcomed, with specific areas highlighted for implementation, including expanding test coverage and developing features like log rotation and dry-run mode.

Licensing & Compatibility

Licensed under the MIT License, permitting broad use, modification, and distribution, including for commercial purposes and integration with closed-source projects.

Limitations & Caveats

Currently at version 0.9.0 with approximately 60% code coverage, indicating ongoing development. Features such as log rotation, dry-run mode, and configuration file support are still in progress. While core functionality is tested, users should anticipate potential evolving behaviors as development continues towards v1.0.0.