How frankbria/ralph-claude-code works
Ralph is a command-line autonomous development loop for Claude Code. A project owner supplies requirements and starts the loop; Ralph repeatedly invokes the coding agent, evaluates responses and progress, and stops only when its completion conditions are met. Rate limits, circuit breaking, and error detection constrain that runtime. Separate capabilities import tasks, enable projects, monitor runs, and report metrics. The README documents these capabilities, but only the E2B helper was sampled from source, so its connection to the loop is shown as unverified.
Main entry points: ralph_loop.sh Development loop · enable_core.sh Enablement workflow · ralph_import.sh Task import · ralph_enable.sh Project enablement
Components 18
Loop runtime
- Development loop
ralph_loop.sh - Claude Code
Runtime safeguards
- Response analysis
lib/response_analyzer.sh - Circuit breaker
lib/circuit_breaker.sh - Rate limiting
lib/timeout_utils.sh
Project workflows
- Task import
ralph_import.sh - Issue analysis
lib/issue_analyzer.sh - Task sources
lib/task_sources.sh - Project enablement
ralph_enable.sh - Enablement workflow
lib/enable_core.sh - Setup wizard
lib/wizard_utils.sh
Run operations
- Live monitor
ralph_monitor.sh - Queue management
ralph_queue.sh - Queue operations
lib/queue_manager.sh - Loop analytics
ralph-stats.sh
Sandbox execution
- E2B transport
lib/e2b_helper.py - E2B sandbox
Other components
- Project owner
Connections 17
- Project owner → Development loop: starts
README.md - Development loop → Claude Code: runs iterations
README.md - Development loop → Response analysis: analyzes output
README.md - Development loop → Circuit breaker: guards runs
README.md - Development loop → Rate limiting: limits calls
README.md - Project owner → Task import: imports tasks
README.md - Task import → Issue analysis: analyzes issues
README.md - Project enablement → Enablement workflow: runs wizard
README.md - Enablement workflow → Setup wizard: uses utilities
README.md - Enablement workflow → Task sources: imports tasks
README.md - Project owner → Project enablement: enables project
README.md - Project owner → Live monitor: monitors runs
README.md - Project owner → Queue management: manages queue
README.md - Queue management → Queue operations: manages tasks
- Project owner → Loop analytics: views metrics
README.md - Development loop → E2B transport: uses transport
- E2B transport → E2B sandbox: connects remotely