Skip to main content
ralph-claude-code - AI Agents | SkillsLLM
Home AI Agents ralph-claude-code Autonomous AI development loop for Claude Code with intelligent exit detection
ai ai-agent ai-agents ai-development ai-development-tools
# Add to your Claude Code skills
git clone https://github.com/frankbria/ralph-claude-codeRalph 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.11.5 - Active Development
Core Features : Working and tested
Test Coverage : 566 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
Sign in with GitHub to leave a comment.
No comments yet. Be the first to share your thoughts!
Related Skills Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
claude-code
claude-code-cli
development-tools
development-workflow
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 --resume flag for context preservation (no session hijacking)
Session expiration with configurable timeout (default: 24 hours)
Modern CLI flags: --output-format, --allowed-tools, --no-continue
Interactive project enablement with ralph-enable wizard
.ralphrc configuration file for project settings
Live streaming output with --live flag for real-time Claude Code visibility
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
Recent Improvements v0.11.5 - Community Bug Fixes (latest)
Fixed API limit false positive: Timeout (exit code 124) no longer misidentified as API 5-hour limit (#183)
Three-layer API limit detection: timeout guard → structural JSON (rate_limit_event) → filtered text fallback
Unattended mode: API limit prompt now auto-waits on timeout instead of exiting
Fixed bash 3.x compatibility: ${,,} lowercase substitution replaced with POSIX tr (#187)
Added 8 new tests for API limit detection (548 → 566 tests)
v0.11.4 - Bug Fixes & Compatibility
Fixed progress detection: Git commits within a loop now count as progress (#141)
Fixed checkbox regex: Date entries [2026-01-29] no longer counted as checkboxes (#144)
Fixed session hijacking: Use --resume <session_id> instead of --continue (#151)
Fixed EXIT_SIGNAL override: STATUS: COMPLETE with EXIT_SIGNAL: false now continues working (#146)
Fixed ralph-import hanging indefinitely (added --print flag for non-interactive mode)
Fixed ralph-import absolute path handling
Fixed cross-platform date commands for macOS with Homebrew coreutils
Added configurable circuit breaker thresholds via environment variables (#99)
Added tmux support for non-zero base-index configurations
Added 13 new regression tests for progress detection and checkbox regex
v0.11.3 - Live Streaming & Beads Fix
Added live streaming output mode with --live flag for real-time Claude Code visibility (#125)
Fixed beads task import using correct bd list arguments (#150)
Applied CodeRabbit review fixes: camelCase variables, status-respecting fallback, jq guards
Added 12 new tests for live streaming and beads import improvements
v0.11.2 - Setup Permissions Fix
Fixed issue #136: ralph-setup now creates .ralphrc with consistent tool permissions
Updated default ALLOWED_TOOLS to include Edit, Bash(npm *), and Bash(pytest)
Both ralph-setup and ralph-enable now create identical .ralphrc configurations
Monitor now forwards all CLI parameters to inner ralph loop (#126)
Added 16 new tests for permissions and parameter forwarding
v0.11.1 - Completion Indicators Fix
Fixed premature exit after exactly 5 loops in JSON output mode
completion_indicators now only accumulates when EXIT_SIGNAL: trueAligns with documented dual-condition exit gate behavior
v0.11.0 - Ralph Enable Wizard
Added ralph-enable interactive wizard for enabling Ralph in existing projects
5-phase wizard: Environment Detection → Task Source Selection → Configuration → File Generation → Verification
Auto-detects project type (TypeScript, Python, Rust, Go) and framework (Next.js, FastAPI, Django)
Imports tasks from beads, GitHub Issues, or PRD documents
Added ralph-enable-ci non-interactive version for CI/automation
New library components: enable_core.sh, wizard_utils.sh, task_sources.sh
v0.10.1 - Bug Fixes & Monitor Path Corrections
Fixed ralph_monitor.sh hardcoded paths for v0.10.0 compatibility
Fixed EXIT_SIGNAL parsing in JSON format
Added safety circuit breaker (force exit after 5 consecutive completion indicators)
Fixed checkbox parsing for indented markdown
v0.10.0 - .ralph/ Subfolder Structure (BREAKING CHANGE)
Breaking : Moved all Ralph-specific files to .ralph/ subfolderProject root stays clean: only src/, README.md, and user files remain
Added ralph-migrate command for upgrading existing projects
v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script
Fixed premature exit bug: completion indicators now require Claude's explicit EXIT_SIGNAL: true
Added dedicated uninstall.sh script for clean Ralph removal
v0.9.8 - Modern CLI for PRD Import
Modernized ralph_import.sh to use Claude Code CLI JSON output format
Enhanced error handling with structured JSON error messages
v0.9.7 - Session Lifecycle Management
Complete session lifecycle management with automatic reset triggers
Added --reset-session CLI flag for manual session reset
v0.9.6 - JSON Output & Session Management
Extended parse_json_response() to support Claude Code CLI JSON format
Added session management functions
v0.9.5 - v0.9.0 - PRD import tests, project setup tests, installation tests, prompt file fix, modern CLI commands, circuit breaker enhancements
In Progress Timeline to v1.0 : ~4 weeks | Full roadmap | Contributions welcome!
Features
Autonomous Development Loop - Continuously executes Claude Code with your project requirementsIntelligent Exit Detection - Dual-condition check requiring BOTH completion indicators AND explicit EXIT_SIGNALSession Continuity - Preserves context across loop iterations with automatic session managementSession Expiration - Configurable timeout (default: 24 hours) with automatic session resetRate Limiting - Built-in API call management with hourly limits and countdown timers5-Hour API Limit Handling - Three-layer detection (timeout guard, JSON parsing, filtered text) with auto-wait for unattended modeLive Monitoring - Real-time dashboard showing loop status, progress, and logsTask Management - Structured approach with prioritized task lists and progress trackingProject Templates - Quick setup for new projects with best-practice structureInteractive Project Setup - ralph-enable wizard for existing projects with task importConfiguration Files - .ralphrc for project-specific settings and tool permissionsComprehensive Logging - Detailed execution logs with timestamps and status trackingConfigurable Timeouts - Set execution timeout for Claude Code operations (1-120 minutes)Verbose Progress Mode - Optional detailed progress updates during executionResponse Analyzer - AI-powered analysis of Claude Code responses with semantic understandingCircuit Breaker - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recoveryCI/CD Integration - GitHub Actions workflow with automated testingClean Uninstall - Dedicated uninstall script for complete removalLive Streaming Output - Real-time visibility into Claude Code execution with --live flag
Quick Start Ralph has two phases: one-time installation and per-project setup .
INSTALL ONCE USE MANY TIMES
+-----------------+ +----------------------+
| ./install.sh | -> | ralph-setup project1 |
| | | ralph-enable |
| Adds global | | ralph-import prd.md |
| 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, ralph-setup, ralph-import, ralph-migrate, ralph-enable, and ralph-enable-ci commands to your PATH.
Note : You only need to do this once per system. After i
56,706
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
AI Agents ai-agents anthropic
An open-source AI agent that brings the power of Gemini directly into your terminal.
AI Agents ai ai-agents
An AI SKILL that provide design intelligence for building professional UI/UX multiple platforms
CLI Tools ai-skills antigravity
The agent that grows with you
AI Agents ai ai-agent
A curated list of awesome Claude Skills, resources, and tools for customizing Claude AI workflows
AI Agents agent-skills ai-agents
