Ralph for Claude Code

Autonomous AI development loop with intelligent exit detection and rate limiting

Ralph is an implementation of the Geoffrey Huntley's technique for Claude Code that enables continuous autonomous development cycles he named after Ralph Wiggum. It enables continuous autonomous development cycles where Claude Code iteratively improves your project until completion, with built-in safeguards to prevent infinite loops and API overuse.

Install once, use everywhere - Ralph becomes a global command available in any directory.

Project Status

Version: v0.9.9 - Active Development Core Features: Working and tested Test Coverage: 308 tests, 100% pass rate

What's Working Now

• Autonomous development loops with intelligent exit detection
• Dual-condition exit gate: Requires BOTH completion indicators AND explicit EXIT_SIGNAL
• Rate limiting with hourly reset (100 calls/hour, configurable)
• Circuit breaker with advanced error detection (prevents runaway loops)
• Response analyzer with semantic understanding and two-stage error filtering
• JSON output format support with automatic fallback to text parsing
• Session continuity with --continue flag for context preservation
• Session expiration with configurable timeout (default: 24 hours)
• Modern CLI flags: --output-format, --allowed-tools, --no-continue
• Multi-line error matching for accurate stuck loop detection
• 5-hour API limit handling with user prompts
• tmux integration for live monitoring
• PRD import functionality
• CI/CD pipeline with GitHub Actions
• Dedicated uninstall script for clean removal
• 308 passing tests across 11 test files

Recent Improvements

v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script

• Fixed premature exit bug: completion indicators now require Claude's explicit EXIT_SIGNAL: true
• Added dual-condition check preventing exits when Claude reports work in progress
• Added response_analyzer.sh fix to respect explicit EXIT_SIGNAL over heuristics
• Added dedicated uninstall.sh script for clean Ralph removal
• Session expiration with configurable timeout (default: 24 hours)
• Added 32 new tests for EXIT_SIGNAL behavior and session expiration
• Test count: 308 (up from 276)

v0.9.8 - Modern CLI for PRD Import

• Modernized ralph_import.sh to use Claude Code CLI JSON output format
• JSON output format support with --output-format json for structured responses
• Enhanced error handling with structured JSON error messages
• Improved file verification with JSON-derived status information
• Backward compatibility with older CLI versions (automatic text fallback)
• Added 11 new tests for modern CLI features

v0.9.7 - Session Lifecycle Management

• Complete session lifecycle management with automatic reset triggers
• Session auto-reset on: circuit breaker open, manual interrupt, project completion
• Added --reset-session CLI flag for manual session reset
• Session history tracking (last 50 transitions) for debugging
• Added 26 new tests for session continuity features

v0.9.6 - JSON Output & Session Management

• Extended parse_json_response() to support Claude Code CLI JSON format
• Added session management functions: store_session_id(), get_last_session_id(), should_resume_session()
• Cross-platform epoch time utilities in date_utils.sh
• Added 16 new tests covering Claude CLI format and session management

v0.9.5 - PRD Import Tests

• Added 22 comprehensive tests for ralph_import.sh PRD conversion script
• Tests cover: file format support, output file creation, project naming, error handling

v0.9.4 - Project Setup Tests

• Added 36 comprehensive tests for setup.sh project initialization script
• Tests cover: directory creation, template copying, git initialization

v0.9.3 - Installation Tests

• Added 14 comprehensive tests for install.sh global installation script
• Tests cover: directory creation, command installation, dependency detection

v0.9.2 - Prompt File Fix

• Fixed critical bug: replaced non-existent --prompt-file CLI flag with -p flag
• Modern CLI mode now correctly passes prompt content via -p "$(cat file)"
• Added error handling for missing prompt files in build_claude_command()

v0.9.1 - Modern CLI Commands (Phase 1.1)

• JSON output format support with --output-format json (default)
• Session continuity using --continue flag for cross-loop context
• Tool permissions via --allowed-tools flag
• CI/CD pipeline with kcov coverage reporting

v0.9.0 - Circuit Breaker Enhancements

• Fixed multi-line error matching in stuck loop detection
• Eliminated JSON field false positives (e.g., "is_error": false)
• Added two-stage error filtering for accurate detection

In Progress

• Expanding test coverage
• Log rotation functionality
• Dry-run mode
• Configuration file support (.ralphrc)
• Metrics and analytics tracking
• Desktop notifications
• Git backup and rollback system

Timeline to v1.0: ~4 weeks | Full roadmap | Contributions welcome!

Features

• Autonomous Development Loop - Continuously executes Claude Code with your project requirements
• Intelligent Exit Detection - Dual-condition check requiring BOTH completion indicators AND explicit EXIT_SIGNAL
• Session Continuity - Preserves context across loop iterations with automatic session management
• Session Expiration - Configurable timeout (default: 24 hours) with automatic session reset
• Rate Limiting - Built-in API call management with hourly limits and countdown timers
• 5-Hour API Limit Handling - Detects Claude's 5-hour usage limit and offers wait/exit options
• Live Monitoring - Real-time dashboard showing loop status, progress, and logs
• Task Management - Structured approach with prioritized task lists and progress tracking
• Project Templates - Quick setup for new projects with best-practice structure
• Comprehensive Logging - Detailed execution logs with timestamps and status tracking
• Configurable Timeouts - Set execution timeout for Claude Code operations (1-120 minutes)
• Verbose Progress Mode - Optional detailed progress updates during execution
• Response Analyzer - AI-powered analysis of Claude Code responses with semantic understanding
• Circuit Breaker - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery
• CI/CD Integration - GitHub Actions workflow with automated testing
• Clean Uninstall - Dedicated uninstall script for complete removal

Quick Start

Ralph has two phases: one-time installation and per-project setup.

INSTALL ONCE              USE MANY TIMES
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-setup project2 |
| Adds global     |          | ralph-setup project3 |
| commands        |          | ...                  |
+-----------------+          +----------------------+

Phase 1: Install Ralph (One Time Only)

Install Ralph globally on your system:

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

This adds ralph, ralph-monitor, and ralph-setup commands to your PATH.

Note: You only need to do this once per system. After installation, you can delete the cloned repository if desired.

Phase 2: Initialize New Projects (Per Project)

For each new project you want Ralph to work on:

Option A: Import Existing PRD/Specifications

# Convert existing PRD/specs to Ralph format (recommended)
ralph-import my-requirements.md my-project
cd my-project

# Review and adjust the generated files:
# - PROMPT.md (Ralph instructions)
# - @fix_plan.md (task priorities)
# - specs/requirements.md (technical specs)

# Start autonomous development
ralph --monitor

Option B: Manual Project Setup

# Create blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project

# Configure your project requirements manually
# Edit PROMPT.md with your project goals
# Edit specs/ with detailed specifications
# Edit @fix_plan.md with initial priorities

# Start autonomous development
ralph --monitor

Ongoing Usage (After Setup)

Once Ralph is installed and your project is initialized:

# Navigate to any Ralph project and run:
ralph --monitor              # Integrated tmux monitoring (recommended)

# Or use separate terminals:
ralph                        # Terminal 1: Ralph loop
ralph-monitor               # Terminal 2: Live monitor dashboard

Uninstalling Ralph

To completely remove Ralph from your system:

# Run the uninstall script
./uninstall.sh

# Or if you deleted the repo, download and run:
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash

How It Works

Ralph operates on a simple but powerful cycle:

1. Read Instructions - Loads PROMPT.md with your project requirements
2. Execute Claude Code - Runs Claude Code with current context and priorities
3. Track Progress - Updates task lis