ra_claude (frankbria/ralph-claude-code)

ra_claude (frankbria/ralph-claude-code) | MoltPulse

Autonomous Development Loop - Continuously executes Claude Code with your project requirements
Intelligent Exit Detection - Dual-condition check requiring BOTH completion indicators AND explicit EXIT_SIGNAL
Session Continuity - Preserves context across loop iterations with automatic session management
Session Expiration - Configurable timeout (default: 24 hours) with automatic session reset
Rate Limiting - Built-in API call management with hourly limits and countdown timers
5-Hour API Limit Handling - Three-layer detection (timeout guard, JSON parsing, filtered text) with auto-wait for unattended mode
Live Monitoring - Real-time dashboard showing loop status, progress, and logs
Task Management - Structured approach with prioritized task lists and progress tracking
Project Templates - Quick setup for new projects with best-practice structure
Interactive Project Setup - ralph-enable wizard for existing projects with task import
Configuration Files - .ralphrc for project-specific settings and tool permissions
Comprehensive Logging - Detailed execution logs with timestamps and status tracking
Configurable Timeouts - Set execution timeout for Claude Code operations (1-120 minutes)
Verbose Progress Mode - Optional detailed progress updates during execution
Response Analyzer - AI-powered analysis of Claude Code responses with semantic understanding
Circuit Breaker - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery
CI/CD Integration - GitHub Actions workflow with automated testing
Clean Uninstall - Dedicated uninstall script for complete removal
Live Streaming Output - Real-time visibility into Claude Code execution with --live flag
Docker Sandbox Execution - Run Claude Code in an isolated container with --sandbox docker (resource limits, network policy, secure credential handoff)
E2B Cloud Sandbox Execution - Run Claude Code in an E2B cloud sandbox with --sandbox e2b (file sync, session recovery, cost tracking with --sandbox-max-cost)

INSTALL ONCE              USE MANY TIMES
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-enable         |
| Adds global     |          | ralph-import prd.md  |
| commands        |          | ...                  |
+-----------------+          +----------------------+

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

cd my-existing-project

# Interactive wizard - auto-detects project type and imports tasks
ralph-enable

# Or with specific task source
ralph-enable --from beads
ralph-enable --from github --label "sprint-1"
ralph-enable --from prd ./docs/requirements.md

# Start autonomous development
ralph --monitor

# Convert existing PRD/specs to Ralph format
ralph-import my-requirements.md my-project
cd my-project

# Review and adjust the generated files:
# - .ralph/PROMPT.md (Ralph instructions)
# - .ralph/fix_plan.md (task priorities)
# - .ralph/specs/requirements.md (technical specs)

# Start autonomous development
ralph --monitor

# Create blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project

# Configure your project requirements manually
# Edit .ralph/PROMPT.md with your project goals
# Edit .ralph/specs/ with detailed specifications
# Edit .ralph/fix_plan.md with initial priorities

# Start autonomous development
ralph --monitor

# Navigate to any Ralph project and run:
ralph --monitor              # Integrated tmux monitoring (recommended)

# Or use separate terminals:
ralph                        # Terminal 1: Ralph loop
ralph-monitor               # Terminal 2: Live monitor dashboard

# Run the uninstall script
./uninstall.sh

# Or if you deleted the repo, download and run:
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash

PROMPT.md (high-level goals)
    ↓
specs/ (detailed requirements when needed)
    ↓
fix_plan.md (specific tasks Ralph executes)
    ↓
AGENT.md (build/test commands - auto-maintained)

Loop 5: Claude outputs "Phase complete, moving to next feature"
        → completion_indicators: 3 (high confidence from patterns)
        → EXIT_SIGNAL: false (Claude says more work needed)
        → Result: CONTINUE (respects Claude's explicit intent)

Loop 8: Claude outputs "All tasks complete, project ready"
        → completion_indicators: 4
        → EXIT_SIGNAL: true (Claude confirms done)
        → Result: EXIT with "project_complete"

## High Priority
- [x] Core feature

## Optional
- [ ] Frontend integration   # does NOT block exit
- [ ] SMS notifications      # does NOT block exit

cd my-existing-project
ralph-enable

ralph-enable-ci                              # Sensible defaults
ralph-enable-ci --from github               # Import from GitHub Issues
ralph-enable-ci --project-type typescript   # Override detection
ralph-enable-ci --json                      # Machine-readable output

# Convert a markdown PRD
ralph-import product-requirements.md my-app

# Convert a text specification
ralph-import requirements.txt webapp

# Convert a JSON API spec
ralph-import api-spec.json backend-service

# Let Ralph auto-name the project from filename
ralph-import design-doc.pdf

# Import a specific issue by number
ralph-import --github-issue 42

# Import the oldest open issue matching a search
ralph-import --github-search "fix login timeout"

# Import the oldest open issue with a label
ralph-import --github-label "sprint-1"

# Fetch from a specific repository (default: repo of the current directory)
ralph-import --github-issue 42 --repo myorg/myrepo

# Override the auto-generated project name (slug of the issue title)
ralph-import --github-issue 42 my-project

# Also import issue comments (e.g. when a plan was posted as a comment)
ralph-import --github-issue 42 --include-comments

# Issues carrying ALL listed labels (comma = AND)
ralph-import --github-label "bug,P0"

# High-priority bugs assigned to me
ralph-import --github-label "bug,P0" --github-assignee @me

# Unassigned issues with a label, skipping anything marked wontfix
ralph-import --github-label "good-first-issue" --github-assignee none --exclude-label wontfix

# Title pattern: * matches anything, everything else is literal (case-insensitive)
ralph-import --github-title "[P0]*"

# Milestone, including closed issues
ralph-import --github-milestone "v1.0" --github-state all

ralph-import --github-label bug --select first        # oldest issue (default)
ralph-import --github-label bug --select interactive  # numbered menu to choose from
ralph-import --github-label bug --select priority     # highest-priority label

ralph-import --github-label bug --dry-run

# Default: assess the issue, generate a plan only if it lacks detail
ralph-import --github-issue 42

# Always generate a plan, with a specific model
ralph-import --github-issue 42 --generate-plan --plan-model opus

# Never generate a plan (fails if the issue scores below the threshold)
ralph-import --github-issue 42 --no-generate-plan

# Tune the threshold and skip the approval prompt (automation/CI)
ralph-import --github-issue 42 --completeness-threshold 75 --auto-approve

# Post a progress comment to the issue every 5 loops while developing
ralph --github-issue 69 --comment-progress --comment-interval 5

# On completion: open a PR linked to the issue, comment a summary, and close it
ralph --github-issue 69 --create-pr --link-issue --close-summary --auto-close

# Add labels when closing, and open a follow-up issue for any TODO/FIXME left in the diff
ralph --github-issue 69 --auto-close --add-label completed \
      --create-followups --followup-label tech-debt

# Open the PR as a draft for manual review before merge
ralph --github-issue 69 --create-pr --draft-pr

# Queue issues by metadata filter (reuses the import filter flags)
ralph-queue add --github-label "bug,P0"
ralph-queue add --github-milestone "v1.0"

# Queue specific issues by number
ralph-queue add --github-issues 69,70,71

# Queue a local PRD/spec file
ralph-queue add --prd ./docs/feature.md

ralph-queue status            # Show the queue (counts + items); --json for machine output
ralph-queue next              # Print the id of the next ready item
ralph-queue reorder           # Sort the queue by priority (P0 first)
ralph-queue validate          # Check for circular dependencies
ralph-queue remove 69         # Remove an item by issue number or id
ralph-queue clear             # Empty the queue

# Process all ready pending items in priority/dependency order
ralph --process-queue
ralph-queue process

# Stop at the first failure instead of skipping it
ralph --process-queue --halt-on-failure

# Resume after an interruption (only pending items are picked up)
ralph --resume-queue

# One time: pull the official image (published on release tags)...
docker pull ghcr.io/frankbria/ralph-sandbox:latest
docker tag ghcr.io/frankbria/ralph-sandbox:latest ralph-sandbox:latest

# ...or build it yourself (from a source checkout, or ~/.ralph after install)
docker build -t ralph-sandbox .

ralph --sandbox docker                          # Default image, 4g RAM, 2 CPUs, bridge network
ralph --sandbox docker --sandbox-image node:20  # Any image with `claude` on PATH
ralph --sandbox docker --sandbox-memory 8g --sandbox-cpus 4
ralph --sandbox docker --sandbox-network none   # Full network isolation (blocks the Claude API —
                                                # only for images with their own auth/proxy setup)
ralph --monitor --sandbox docker                # Works with tmux monitoring

pip install e2b                       # official E2B Python SDK (the transport)
export E2B_API_KEY="e2b_..."          # or: store in ~/.ralph/e2b_api_key (chmod 600)

ralph --sandbox e2b                                   # base template; claude CLI auto-bootstrapped
ralph --sandbox e2b --sandbox-template my-template    # custom template with claude preinstalled
ralph --sandbox e2b --sandbox-timeout 7200            # 2h session timeout (expired sandboxes auto-recreate)
ralph --sandbox e2b --sandbox-max-cost 5.00 --sandbox-cost-alert 2.00   # budget controls
ralph --sandbox e2b --sandbox-keep-alive              # leave it running; reuse with --sandbox-id <id>
ralph --monitor --sandbox e2b                         # works with tmux monitoring (cost shown in the dashboard)

# Sync filtering (Issue #76): control what uploads/downloads
ralph --sandbox e2b --sync-include "src/**,tests/**,*.md" --sync-exclude "*.log,node_modules"

# .ralphrc - Ralph project configuration
PROJECT_NAME="my-project"
PROJECT_TYPE="typescript"

# Claude Code CLI command (auto-detected, override if needed)
CLAUDE_CODE_CMD="claude"
# CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code"  # Alternative: use npx

# Shell init file — source before running claude (useful for zsh/fish users
# whose PATH or env vars are only set in their shell's init file)
#RALPH_SHELL_INIT_FILE="~/.zshrc"

# Loop settings
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
# Token budget per hour (0 = disabled). One Claude call can use 100k+ tokens.
#MAX_TOKENS_PER_HOUR=500000

# Tool permissions
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

# Session management
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24

# Circuit breaker thresholds
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5

# Default: 100 calls per hour
ralph --calls 50

# With integrated monitoring
ralph --monitor --calls 50

# Check current usage (shows calls and tokens used this hour)
ralph --status

# Default: 30-minute cooldown before auto-recovery attempt
CB_COOLDOWN_MINUTES=30     # Set in .ralphrc (0 = immediate)

# Auto-reset on startup (for fully unattended operation)
ralph --auto-reset-circuit
# Or set in .ralphrc: CB_AUTO_RESET=true

# Use custom prompt file
ralph --prompt my_custom_instructions.md

# With integrated monitoring
ralph --monitor --prompt my_custom_instructions.md

# Set Claude Code execution timeout (default: 15 minutes)
ralph --timeout 30  # 30-minute timeout for complex tasks

# With monitoring and custom timeout
ralph --monitor --timeout 60  # 60-minute timeout

# Short timeout for quick iterations
ralph --verbose --timeout 5  # 5-minute timeout with progress

# Enable detailed progress updates during execution
ralph --verbose

# Combine with other options
ralph --monitor --verbose --timeout 30

# Enable real-time visibility into Claude Code execution
ralph --live

# Combine with monitoring for best experience
ralph --monitor --live

# Live output is written to .ralph/live.log
tail -f .ralph/live.log  # Watch in another terminal

# Sessions are enabled by default with --continue flag
ralph --monitor                 # Uses session continuity

# Start fresh without session context
ralph --no-continue             # Isolated iterations

# Reset session manually (clears context)
ralph --reset-session           # Clears current session

# Check session status
cat .ralph/.ralph_session              # View current session file
cat .ralph/.ralph_session_history      # View session transition history

MAX_CONSECUTIVE_TEST_LOOPS=3     # Exit after 3 test-only loops
MAX_CONSECUTIVE_DONE_SIGNALS=2   # Exit after 2 "done" signals
TEST_PERCENTAGE_THRESHOLD=30     # Flag if 30%+ loops are test-only

CB_NO_PROGRESS_THRESHOLD=3       # Open circuit after 3 loops with no file changes
CB_SAME_ERROR_THRESHOLD=5        # Open circuit after 5 loops with repeated errors
CB_OUTPUT_DECLINE_THRESHOLD=70   # Open circuit if output declines by >70%
CB_COOLDOWN_MINUTES=30           # Minutes before OPEN → HALF_OPEN auto-recovery
CB_AUTO_RESET=false              # true = reset to CLOSED on startup (bypasses cooldown)

my-project/
├── .ralph/                 # Ralph configuration and state (hidden folder)
│   ├── PROMPT.md           # Main development instructions for Ralph
│   ├── fix_plan.md        # Prioritized task list
│   ├── AGENT.md           # Build and run instructions
│   ├── specs/              # Project specifications and requirements
│   │   └── stdlib/         # Standard library specifications
│   ├── examples/           # Usage examples and test cases
│   ├── logs/               # Ralph execution logs
│   └── docs/generated/     # Auto-generated documentation
├── .ralphrc                # Ralph configuration file (tool permissions, settings)
└── src/                    # Source code implementation (at project root)

# Install BATS testing framework
npm install -g bats bats-support bats-assert

# Run unit + integration tests (771 tests)
npm test

# Run end-to-end tests (13 tests; full ralph_loop.sh subprocess runs)
npm run test:e2e

# Run specific test suites
bats tests/unit/test_rate_limiting.bats
bats tests/unit/test_exit_detection.bats
bats tests/unit/test_json_parsing.bats
bats tests/unit/test_cli_modern.bats
bats tests/unit/test_cli_parsing.bats
bats tests/unit/test_session_continuity.bats
bats tests/unit/test_enable_core.bats
bats tests/unit/test_task_sources.bats
bats tests/unit/test_ralph_enable.bats
bats tests/unit/test_wizard_utils.bats
bats tests/unit/test_circuit_breaker_recovery.bats
bats tests/integration/test_loop_execution.bats
bats tests/integration/test_prd_import.bats
bats tests/integration/test_project_setup.bats
bats tests/integration/test_installation.bats

# Run error detection and circuit breaker tests
./tests/test_error_detection.sh
./tests/test_stuck_loop_detection.sh

# Ubuntu/Debian
sudo apt-get install tmux

# macOS
brew install tmux

# CentOS/RHEL
sudo yum install tmux

# Install coreutils (provides gtimeout)
brew install coreutils

# Verify installation
gtimeout --version

# Integrated tmux monitoring (recommended)
ralph --monitor

# Manual monitoring in separate terminal
ralph-monitor

# JSON status output
ralph --status

# Manual log inspection
tail -f .ralph/logs/ralph.log

# Fork and clone
git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
cd ralph-claude-code

# Install dependencies and run tests
npm install
npm test && npm run test:e2e  # All 784 tests must pass

./install.sh              # Install Ralph globally
./uninstall.sh            # Remove Ralph from system (dedicated script)
./install.sh uninstall    # Alternative: Remove Ralph from system
./install.sh --help       # Show installation help
ralph-migrate             # Migrate existing project to .ralph/ structure

ralph [OPTIONS]
  -h, --help              Show help message
  -c, --calls NUM         Set max calls per hour (default: 100)
  -p, --prompt FILE       Set prompt file (default: .ralph/PROMPT.md)
  -s, --status            Show current status and exit
  -m, --monitor           Start with tmux session and live monitor
  -v, --verbose           Show detailed progress updates during execution
  -l, --live              Enable live streaming output (real-time Claude Code visibility)
  -t, --timeout MIN       Set Claude Code execution timeout in minutes (1-120, default: 15)
  --dry-run               Simulate loop execution without making actual Claude API calls
  -n, --notify            Enable desktop notifications for key events
  -b, --backup            Enable automatic git backup branch before each loop (requires git)
  --rollback [BRANCH]     Roll back to a backup branch (lists available branches if none given)
  --show-tool-args        Show tool arguments (commands, file paths) in live streaming output
  --output-format FORMAT  Set output format: json (default) or text
  --allowed-tools TOOLS   Set allowed Claude tools (default: granular git subcommands + npm/pytest)
  --no-continue           Disable session continuity (start fresh each loop)
  --session-expiry HOURS  Set session expiration time in hours (default: 24)
  --reset-circuit         Reset the circuit breaker
  --circuit-status        Show circuit breaker status
  --auto-reset-circuit    Auto-reset circuit breaker on startup (bypasses cooldown)
  --reset-session         Reset session state manually
  --queue-status          Show the issue queue and exit
  --process-queue         Process pending queued issues sequentially (--halt-on-failure to stop on first failure)
  --resume-queue          Resume processing the remaining pending issues
  --queue-next            Print the id of the next ready queued issue
  --queue-clear           Remove all items from the queue
  --queue-remove <id|N>   Remove one item from the queue

ralph-setup project-name     # Create new Ralph project
ralph-enable                 # Enable Ralph in existing project (interactive)
ralph-enable-ci              # Enable Ralph in existing project (non-interactive)
ralph-import prd.md project  # Convert PRD/specs to Ralph project
ralph-queue add --github-label bug   # Build a batch queue of issues
ralph-queue status           # Show the issue queue
ralph --process-queue        # Process the queue sequentially
ralph --monitor              # Start with integrated monitoring
ralph --status               # Check current loop status
ralph --verbose              # Enable detailed progress updates
ralph --timeout 30           # Set 30-minute execution timeout
ralph --calls 50             # Limit to 50 API calls per hour
ralph --reset-session        # Reset session state manually
ralph --live                 # Enable live streaming output
ralph --dry-run              # Simulate a loop without API calls
ralph --notify               # Desktop notifications for key events
ralph --backup               # Git backup branch before each loop
ralph-stats                  # Metrics summary from .ralph/logs/metrics.jsonl
ralph-monitor                # Manual monitoring dashboard

tmux list-sessions        # View active Ralph sessions
tmux attach -t <name>     # Reattach to detached session
# Ctrl+B then D           # Detach from session (keeps running)

ra_claude

MoltPulse

Ralph for Claude Code

Project Status

What's Working Now

Recent Improvements

In Progress

Features

Quick Start

Phase 1: Install Ralph (One Time Only)

Phase 2: Initialize Projects (Per Project)

Option A: Enable Ralph in Existing Project (Recommended)

Option B: Import Existing PRD/Specifications

Option C: Create New Project from Scratch

Ongoing Usage (After Setup)

Uninstalling Ralph

Understanding Ralph Files

Key File Relationships

When to Use specs/

How It Works

Intelligent Exit Detection

Optional / Future sections in fix_plan.md

Enabling Ralph in Existing Projects

Importing Existing Requirements

Supported Formats

Usage Examples

What Gets Generated

Importing from GitHub Issues

Prerequisites

Usage Examples

Filtering and Selecting Issues by Metadata

Completeness Assessment and Plan Generation

Troubleshooting

GitHub Issue Lifecycle

Batch Processing and Issue Queue

Building a queue

Managing the queue

Processing the queue

Docker Sandbox Execution

Setup

Usage

How credentials reach the container

E2B Cloud Sandbox Execution

Setup

Usage

Configuration

Project Configuration (.ralphrc)

Rate Limiting & Circuit Breaker

Claude API 5-Hour Limit

Custom Prompts

Execution Timeouts

Verbose Mode

Live Streaming Output

Session Continuity

Exit Thresholds

Project Structure

Best Practices

Writing Effective Prompts

Project Specifications

Monitoring Progress

System Requirements

Testing Requirements (Development)

Installing tmux

Installing GNU coreutils (macOS)

Monitoring and Debugging

Live Dashboard

Status Checking

Common Issues

Contributing

Quick Start

Priority Contribution Areas

License

Acknowledgments

Related Projects

Command Reference

Installation Commands (Run Once)

Ralph Loop Options

Project Commands (Per Project)

tmux Session Management

Development Roadmap