ralph-claude-code

Name: ralph-claude-code
Author: frankbria

Verified

Autonomous AI development loop for Claude Code with intelligent exit detection

9,524stars

726forks

Shell

Installation

# Add to your Claude Code skills
git clone https://github.com/frankbria/ralph-claude-code

Getting Started

Guides for using ai agents skills like ralph-claude-code.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportVerified

Last scanned: 4/18/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-04-18T05:42:04.534Z",
  "semgrepRan": false,
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is ralph-claude-code?

ralph-claude-code is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by frankbria. Autonomous AI development loop for Claude Code with intelligent exit detection. It has 9,524 GitHub stars.

Is ralph-claude-code safe to use?

Yes. ralph-claude-code passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install ralph-claude-code?

Clone the repository with "git clone https://github.com/frankbria/ralph-claude-code" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is ralph-claude-code written in?

ralph-claude-code is primarily written in Shell. It is open-source under frankbria on GitHub, so you can review or fork the full source.

Are there alternatives to ralph-claude-code?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh ralph-claude-code against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

Developers Also Liked

Based on votes and bookmarks from developers who liked this skill

everything-claude-code

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

185,940

stop-slop QuantDinger

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.11.5 - Active Development Core Features: Working and tested Test Coverage: 784 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 --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
Log rotation: ralph.log rotates at 10MB, keeping 4 archived files
Dry-run mode (--dry-run) to simulate loops without API calls
Metrics tracking with ralph-stats analytics command (JSON Lines per-loop metrics)
Desktop notifications (--notify) for key loop events (macOS/Linux/terminal-bell)
Automatic git backup branches (--backup) with --rollback restore
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
GitHub issue import: ralph-import --github-issue plus metadata filters (labels, title, assignee, milestone, state) with first/interactive/priority selection and --dry-run preview
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: true
Aligns 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/ subfolder
Project 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

Expanding test coverage
Automated badge updates
Multi-provider agent abstraction — decoupling Ralph from claude so any headless coding CLI (Codex, Gemini, OpenCode, Droid, Kilocode, Copilot) can drive the loop (multi-provider epic; see also the agent adapter contract)

Timeline to v1.0: final polish underway | 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 - Three-layer detection (timeout guard, JSON parsing, filtered text) with auto-wait for unattended mode
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
Interactive Project Setup - ralph-enable wizard for existing projects with task import
Configuration Files - .ralphrc for project-specific settings and tool permissions
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 uninsta