The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
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:
Read Instructions - Loads PROMPT.md with your project requirements
Execute Claude Code - Runs Claude Code with current context and priorities
Track Progress - Updates task lists and logs execution results
Evaluate Completion - Checks for exit conditions and project completion signals
Repeat - Continues until project is complete or limits are reached
Intelligent Exit Detection
Ralph uses a dual-condition check to prevent premature exits during productive iterations:
Exit requires BOTH conditions:
completion_indicators >= 2 (heuristic detection from natural language patterns)
Claude's explicit EXIT_SIGNAL: true in the RALPH_STATUS block
Example behavior:
Loop 5: Claude outputs "Phase complete, moving to next feature"
→ completion_indicators: 3 (high confidence from patterns)
→ EXIT_SIGNAL: false (Claude says more work needed)
→ Result: CONTINUE (respects Claude's explicit