Autonomous AI development loop for Claude Code, enabling continuous project improvement with intelligent exit detection and API overuse safeguards. It targets engineers and power users seeking to automate AI-driven development cycles, offering benefits like iterative self-improvement, robust error handling, and efficient API usage management.

How It Works

Ralph implements an autonomous development loop inspired by Geoffrey Huntley's technique. It iteratively reads project instructions from PROMPT.md, executes Claude Code, tracks progress, and evaluates completion signals. A novel dual-condition exit gate requires both heuristic completion indicators and an explicit EXIT_SIGNAL: true from Claude to terminate a loop, preventing premature exits. Rate limiting and an advanced circuit breaker with multi-line error matching further safeguard against infinite loops and API abuse.

Quick Start & Requirements

• Primary install / run command:
  • One-time global installation: git clone https://github.com/DmitrySolana/ralph-claude-code.git, cd ralph-claude-code, ./install.sh. This adds ralph, ralph-monitor, and ralph-setup commands.
  • Per-project setup: ralph-setup <project-name> or ralph-import <requirements.md> <project-name>.
  • Start development: ralph --monitor (integrated tmux monitoring) or ralph and ralph-monitor in separate terminals.
• Non-default prerequisites and dependencies:
  • Claude Code CLI (npm install -g @anthropic-ai/claude-code)
  • tmux (for integrated monitoring)
  • jq (for JSON status tracking)
  • Git
  • Bash 4.0+
• Estimated setup time or resource footprint: Installation is a one-time script execution. Project setup involves reviewing generated files. Standard CLI resource usage.
• Links: GitHub Repository, CONTRIBUTING.md

Highlighted Details

• Intelligent Exit Detection: Dual-condition gate requiring completion indicators and explicit EXIT_SIGNAL: true prevents premature loop termination.
• Session Continuity & Expiration: Preserves context across loop iterations with automatic session management and a configurable 24-hour expiration.
• Rate Limiting & Circuit Breaker: Manages API calls (default 100/hour, configurable) and employs advanced error detection, multi-line matching, and two-stage filtering to prevent stuck loops.
• PRD Import Functionality: Converts existing Markdown, text, JSON, DOCX, or PDF documents into Ralph's structured project format using Claude Code.
• Modern CLI Features: Supports JSON output format (default) and structured error parsing, requiring Claude Code CLI v2.0.76+.

Maintenance & Community

The project is under active development (v0.9.9) with a clear roadmap towards v1.0.0. Contributions are welcomed, with detailed guidelines provided in CONTRIBUTING.md. Priority areas for contribution include test implementation, feature development (log rotation, dry-run), and documentation.

Licensing & Compatibility

This project is licensed under the MIT License, which is permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

The project is actively developed, with several features listed as "In Progress" (e.g., log rotation, dry-run mode, configuration files). While the test suite boasts a 100% pass rate across 308 tests, bash code coverage has inherent limitations. Full utilization of modern CLI features requires a specific version of the Claude Code CLI.