[opensourcedex]

ralph-claude-code is a free, open source ai development platforms project written in Shell and released under MIT. It has 9,637 GitHub stars, 719 forks and 37 open issues, and was last pushed 2 months ago. On this registry it ranks #60 of 116 tracked projects in AI Development Platforms, with 5 head-to-head comparisons available.

What is ralph-claude-code?

Ralph for Claude Code is an MIT-licensed Shell tool that turns Claude Code into a continuous autonomous development loop with intelligent exit detection and rate limiting, built for developers who want an AI agent to work through a backlog without a human re-prompting every iteration.

What it is

Ralph for Claude Code is a command-line implementation of the technique Geoffrey Huntley described for Claude Code, which he named after Ralph Wiggum. It repeatedly invokes Claude Code so that the agent iteratively improves a project until it reaches completion, and it wraps that repetition in safeguards such as a dual-condition exit gate, a circuit breaker, and rate limiting. The project is written in Shell, distributed under the MIT licence, and installs once as a global command that is then available in any directory.

The concrete problem it solves is the manual supervision loop that otherwise surrounds agentic coding: a developer writes a prompt, waits, reads the result, decides whether work remains, and writes another prompt. Ralph replaces that hand-driven cycle with an automated one, and it replaces the naive shell loop that would otherwise serve the same purpose by adding completion detection, API limit handling, multi-line error matching for stuck-loop detection, and progress detection that counts git commits made inside a loop as progress. It lives in the Claude Code ecosystem, so its prompts, flags, and session handling are those of the Claude Code CLI.

Key capabilities

  • Dual-condition exit gate: the loop stops only when completion indicators and an explicit EXIT_SIGNAL both appear, so STATUS: COMPLETE with EXIT_SIGNAL: false keeps working.
  • Rate limiting with an hourly reset at 100 calls per hour, which is configurable, plus a circuit breaker with advanced error detection to prevent runaway loops.
  • Session continuity through the --resume flag rather than --continue, which preserves context without session hijacking, with configurable session expiration that defaults to 24 hours.
  • JSON output format with automatic fallback to text parsing, alongside the --output-format, --allowed-tools, and --no-continue flags.
  • ralph-enable interactive project enablement wizard and the .ralphrc configuration file for per-project settings.
  • ralph-import --github-issue with metadata filters for labels, title, assignee, milestone, and state, offering first, interactive, and priority selection plus a --dry-run preview.
  • Observability and safety tooling: ralph-stats metrics in JSON Lines per-loop format, --live streaming output, tmux integration, --notify desktop notifications, and ralph.log rotation at 10MB keeping 4 archived files, together with --dry-run simulation and automatic git backup branches via --backup with --rollback restore.

Who uses it and how

  • Individual developers and small teams run it for unattended development cycles, where the unattended mode now auto-waits on an API limit timeout instead of exiting.
  • Teams with a GitHub issue backlog import work directly through ralph-import --github-issue, filtering by label, assignee, milestone, or state and previewing the selection with --dry-run.
  • Projects that already have a written specification use the PRD import functionality to seed the loop.
  • Operators monitoring long runs watch progress through tmux integration or the --live flag, and rely on --backup branches with --rollback to recover a working tree.

Getting started

The README describes installing Ralph once so that it becomes a global command available in any directory, after which a project is enabled through the ralph-enable wizard and configured through .ralphrc. The provided facts do not name a package manager, Docker image, or compose file, so installation specifics are not documented here.

How it compares

No list of paid products that this project replaces is provided in the facts, and no similar tools are named. On the evidence available, it stands alone in this registry.

When to use it — and when not to

A self-hoster must already have the Claude Code CLI and an API allowance that tolerates the configured rate limit, should keep the target project under git for the backup and rollback features, and needs tmux only if live monitoring is wanted, since desktop notifications depend on macOS, Linux, or a terminal bell. It is a poor fit for anyone who wants to review every generated step before it lands, because the whole point is an unattended loop that commits as it goes. The honest weakness is maturity: the current version is v0.11.5 with active development, 37 open issues, and a recent round of fixes for an API-limit false positive and for Bash 3.x compatibility, which shows how much of the behaviour depends on fragile text and process-signal parsing.

project readme (upstream, from github) — read inline

Ralph for Claude Code

CI License: MIT Version Tests GitHub Issues Mentioned in Awesome Claude Code Follow on X

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 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
Earlier versions (v0.9.x)

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: 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

readme truncated — read the full docs on github

Frequently asked questions

Is ralph-claude-code free to use?

ralph-claude-code is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ralph-claude-code do?

Autonomous AI development loop for Claude Code with intelligent exit detection

What is ralph-claude-code written in?

ralph-claude-code is primarily written in Shell. Its source is publicly available at https://github.com/frankbria/ralph-claude-code, and it has 9,637 GitHub stars.