Ralph for Claude Code

Ralph for Claude Code — Detailed Introduction

Ralph is an implementation of Geoffrey Huntley’s "Ralph" technique adapted for Anthropic's Claude Code. It provides an autonomous development loop that continuously runs Claude Code against a project's instructions, tracks progress, and stops automatically when completion conditions are met or when safety limits are reached.

Key Capabilities

• Autonomous development loop: Continuously executes Claude Code with project-specific prompts and context until objectives are satisfied.
• Intelligent exit detection: Multiple heuristics detect completion (e.g., all tasks in @fix_plan.md marked done, repeated "done" signals, excessive test-focused loops) to avoid endless runs.
• Rate limiting & API management: Default rate limit of 100 calls/hour (configurable) with built-in countdown and usage reporting.
• Circuit breaker: Two-stage error filtering, multi-line error matching, and thresholds that open the circuit on repeated failures to prevent runaway behavior.
• Response analyzer: Semantic analysis of Claude Code outputs with fallback parsing for text and robust JSON output support.
• Session continuity: --continue flag preserves context across loops; --no-continue forces fresh starts.
• Monitoring: Integrated tmux dashboard (ralph --monitor / ralph-monitor) for live loop status, API usage, and recent logs.
• Project import: ralph-import converts PRDs/specs (.md/.pdf/.docx/.json etc.) into a Ralph project structure (PROMPT.md, @fix_plan.md, specs/).

Current Status (from repository)

• Version: v0.9.3 (active development)
• Test suite: 165 tests with 100% pass rate
• Core features implemented and tested: loop execution, exit detection, rate limiting, circuit breaker, JSON output, session continuity, CI/CD integration

How it works (workflow)

1. Ralph reads project instructions from PROMPT.md and @fix_plan.md.
2. It runs Claude Code commands with the current context and receives responses.
3. A response analyzer evaluates outputs, updates task progress, and decides whether to continue.
4. The circuit breaker and rate limiter monitor errors and API usage; when thresholds are hit Ralph pauses or exits and prompts the user.
5. The loop repeats until completion conditions or user-configured limits are met.

Installation & Usage (summary)

• One-time install: clone the repo and run ./install.sh to add ralph, ralph-monitor, and ralph-setup to PATH.
• Initialize a project: ralph-setup <project> or ralph-import <prd> <project>.
• Run: ralph --monitor (recommended) or ralph with flags such as --timeout, --calls, --prompt, --output-format.

Configuration & Safety

• Default exit and breaker thresholds are configurable via ~/.ralph/ralph_loop.sh variables (e.g., MAX_CONSECUTIVE_TEST_LOOPS, CB_NO_PROGRESS_THRESHOLD).
• Handles Claude’s 5-hour usage error by prompting to wait or exit; also supports configurable execution timeouts (1–120 minutes).

Project structure & testing

• Standardized project layout (PROMPT.md, @fix_plan.md, specs/, src/, logs/, docs/generated/).
• Tests: ready-to-run BATS-based test suites; instructions included for running unit and integration tests.

Contribution & roadmap

• The project is actively seeking contributors to help with log rotation, dry-run mode, config file support (.ralphrc), metrics, notifications, and backup/rollback features on the path to v1.0.0.

Notes

Ralph is specifically designed to orchestrate and manage Claude Code autonomous loops; it depends on Claude Code CLI and standard Unix tooling (bash 4+, tmux, jq, git). The repository README documents usage, CLI options, and developer guidelines in detail.