$ show frankbria/ralph-claude-code
Ralph for Claude Code is a CLI automation framework written entirely in Bash (with one Python helper for E2B sandbox transport) that orchestrates repeated Claude Code CLI invocations in an autonomous loop. The core system parses output from Claude to detect completion, test saturation, permission denials, and stuck loops, using a dual-condition exit strategy. It includes a circuit breaker (CLOSED/HALF_OPEN/OPEN) for stagnation protection, dual rate limiting (calls and tokens per hour), sandbox execution via Docker or E2B cloud, session continuity with expiry, and backup/rollback via git branches. The system manages GitHub issue lifecycles (progress comments, auto-close, PR creation, follow-up issues) and provides a persistent queue for batch processing with dependency resolution and priority ordering. All state is maintained as JSON files in a .ralph directory with atomic writes. The repository also includes extensive test infrastructure (276 BATS tests) with mock binaries for gh, claude, docker, and e2b-python, a full E2E subprocess-level harness, and 24 unit test files plus integration and E2E tests. The project is not a hybrid data/research repository; it is purely an application for automating AI-assisted software development.
The LLM identified 4 files worth highlighting for reuse:
Implements a generic three-state circuit breaker (CLOSED/HALF_OPEN/OPEN) with configurable stagnation detection, cooldown timers, auto-reset on timeout, and persistent state via temp+mv atomic file writes. The pattern is self-contained (no internal imports beyond utility functions) and could be extracted into any Bash project requiring fault tolerance.
Provides a persistent JSON-based queue with priority sorting, circular dependency detection, status transitions (queued/active/completed/failed), and a get_next_issue function that selects the highest-priority item with satisfied dependencies. The module is self-contained with no internal imports and could be reused in any Bash project needing ordered, dependency-aware batch processing.
Backend-agnostic file sync filtering with a pipeline: include globs → exclude globs → .ralphignore (gitignore-like) → size policy. Upload uses NUL-separated xargs for safe transfer; download uses -T list with hard exclusions (.git, .ralph subdirs). The module is self-contained and could be extracted for any project needing portable, configurable file filtering.
Provides a complete subprocess-level E2E test harness with mock binaries for claude, docker, and e2b-python, supporting queue_response, queue_productive_effect, and assert_call_count with hour-boundary-aware timing. The harness uses file-based call logging and isolated HOME/temp directories, enabling deterministic testing of autonomous loops without real API calls. This pattern is reusable for any project needing to test CLI orchestrators with mock external commands.