frankbria/ralph-claude-code

What it solves

Ralph solves the problem of turning a single Claude Code invocation into a full, unattended development cycle. Instead of repeatedly prompting Claude by hand, Ralph runs Claude Code in a loop that reads project instructions, executes code changes, tracks progress, and repeats until the project is genuinely complete. It also guards against the two common failure modes of such loops: running forever because the exit signal is misread, and burning through the API hourly or 5-hour limits.

How it works

Ralph runs a cycle: it loads a project's instructions from .ralph/PROMPT.md, executes Claude Code with the current context, then updates task lists and logs. It checks completion using a dual-condition gate: both a heuristic count of completion indicators (at least 2 from natural language patterns) AND Claude's explicit EXIT_SIGNAL: true in its output must be present. If either is missing, the loop continues. Ralph also uses a circuit breaker that force-exits after several consecutive done-signals, rate limiting with an hourly cap (default 100 calls), a 5-hour API limit detector with three-layer detection, and session management with --resume for context preservation. It can stream live output with --live, run in a Docker or E2B sandbox, and auto-back up git state.

Who it's for

Ralph is for developers who use Claude Code and want to delegate longer, multi-step coding tasks to an autonomous agent loop. It is especially useful for turning product requirements documents (PRDs) or GitHub issues into a working codebase with minimal manual prompting. It also suits teams that need unattended progress on well-defined task lists.

Highlights

• Dual-condition exit detection (completion indicators + explicit EXIT_SIGNAL) to avoid premature or infinite loops.
• Rate limiting with hourly reset and a circuit breaker to prevent API overuse and runaway loops.
• Session continuity with --resume (no session hijacking) and configurable session expiration (default 24 hours).
• Three-layer detection of the 5-hour API limit, including timeout guard, JSON parsing, and text fallback.
• Interactive ralph-enable wizard that auto-detects project type and imports tasks from beads, GitHub Issues, or PRDs.
• ralph-import converts markdown, text, JSON, DOCX, and PDF requirement documents into structured Ralph projects.
• Docker and E2B cloud sandbox execution with resource limits and cost tracking.
• Optional live streaming, desktop notifications, dry-run mode, and automatic git backup branches with rollback.