--- title: "ralph-claude-code" type: "tool" slug: "frankbria-ralph-claude-code" canonical_url: "https://www.graphcanon.com/tools/frankbria-ralph-claude-code" github_url: "https://github.com/frankbria/ralph-claude-code" homepage_url: null stars: 9511 forks: 726 primary_language: "Shell" license: "MIT" categories: ["ai-agents", "developer-tools"] tags: ["rate-limiting", "session-continuity", "exit-detection", "ai", "claude-code", "ai-agents", "autonomous-developmment", "development-tools"] updated_at: "2026-07-07T18:34:59.112547+00:00" --- # ralph-claude-code > Autonomous AI development loop with intelligent exit detection Ralph is an autonomous AI development tool that helps Claude Code iteratively improve projects, complete them autonomously with safeguards to avoid infinite loops and excessive API usage. ## Facts - Repository: https://github.com/frankbria/ralph-claude-code - Stars: 9,511 · Forks: 726 · Open issues: 25 · Watchers: 46 - Primary language: Shell - License: MIT - Last pushed: 2026-07-04T02:33:21+00:00 ## Categories - [AI Agents](/categories/ai-agents.md) - [Developer Tools](/categories/developer-tools.md) ## Tags rate-limiting, session-continuity, exit-detection, ai, claude-code, ai-agents, autonomous-developmment, development-tools ## Related tools - [ECC](/tools/affaan-m-ecc.md) - The agent harness performance optimization system (★ 226,962) - [hermes-agent](/tools/nousresearch-hermes-agent.md) - The self-improving AI agent built by Nous Research (★ 210,880) - [AutoGPT](/tools/significant-gravitas-autogpt.md) - AutoGPT: Build, Deploy, and Run AI Agents (★ 185,417) - [ollama](/tools/ollama-ollama.md) - Get up and running with Kimi-K2.6, GLM-5.1, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models. (★ 175,659) - [prompts.chat](/tools/f-prompts-chat.md) - The world's largest open-source prompt library for AI (★ 165,019) - [JavaGuide](/tools/snailclimb-javaguide.md) - Snailclimb/JavaGuide: 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发 (★ 156,863) - [langflow](/tools/langflow-ai-langflow.md) - Langflow is a powerful platform for building and deploying AI-powered agents and workflows. (★ 151,298) - [dify](/tools/langgenius-dify.md) - Production-ready platform for agentic workflow development (★ 148,070) ## README (excerpt) ```text # 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](https://ghuntley.com/ralph/). 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 ``` --- **Machine-readable endpoints** - JSON: [`/api/graphcanon/tools/frankbria-ralph-claude-code`](/api/graphcanon/tools/frankbria-ralph-claude-code) - LLM index: [/llms.txt](/llms.txt) - Full corpus: [/llms-full.txt](/llms-full.txt) _GraphCanon - The knowledge graph for AI development. https://www.graphcanon.com/_