frankbria/ralph-claude-code Practical Guide

Introduction

The previous article introduced Ralph's methodology, and snarktank/ralph demonstrated a minimalist outer loop implementation. Now let's look at another approach: frankbria/ralph-claude-code.

If snarktank/ralph's philosophy is "do the most with the least code," then frankbria's philosophy is "engineer everything" — interactive configuration wizards, real-time monitoring dashboards, circuit breakers, rate limiting, and session expiration management. It doesn't pursue simplicity; it pursues controllability.

Neither implementation is inherently better — they suit different use cases. This article walks you through frankbria's complete toolchain.

Installation and Configuration

Global Installation

# Clone the repository
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code

# Global install
./install.sh

After installation, you'll have the following global commands:

Project Initialization

For existing projects, use the interactive wizard:

cd your-project
ralph-enable

The wizard automatically detects the project type (Node.js, Python, Go, etc.) and framework (Next.js, FastAPI, etc.), then generates the corresponding configuration files.

For brand-new projects:

ralph-setup my-new-project

This creates the project directory, initializes Git, and generates the .ralph/ configuration directory.

Importing Existing Requirements

If you already have a PRD document or requirements specification:

ralph-import path/to/your-prd.md

Ralph will parse the document, extract the task list, and generate a structured fix_plan.md.

.ralph/ Directory Structure

frankbria's memory and configuration are centralized in the .ralph/ directory:

.ralph/
├── PROMPT.md          # Project goals and context
├── fix_plan.md        # Task checklist (similar role to prd.json)
├── AGENT.md           # Build/test commands (auto-maintained)
├── specs/             # Detailed requirement documents
│   ├── feature-a.md
│   └── feature-b.md
└── sessions/          # Session persistence data
    ├── current.json
    └── history/

Comparison with snarktank/ralph:

Note that AGENT.md is auto-maintained — Ralph automatically updates this file based on project conventions discovered during execution, similar to snarktank/ralph's progress.txt, but more structured.

Core Commands

Basic Execution

# Start the Ralph loop
ralph

# With real-time monitoring
ralph --monitor

# Run in tmux (recommended for long-running tasks)
ralph --live

Monitoring Dashboard

# Launch monitoring independently
ralph-monitor

ralph-monitor opens a tmux dashboard that displays in real time:

• The currently executing task
• Completed/remaining task counts
• API call counts and cost estimates
• Circuit breaker status
• Recent error logs

Common Parameters

# Limit to 50 API calls with a 2-hour timeout
ralph --calls 50 --timeout 120

# Resume from where you left off
ralph --resume

Safety Mechanisms

frankbria's biggest differentiator is its multi-layered safety mechanisms.

Circuit Breaker

The circuit breaker automatically stops the loop when it detects "no progress," preventing wasteful API consumption:

Consecutive no-progress detection: If N consecutive iterations complete without any new task being finished, the circuit breaker triggers.

Repeated error detection: If the same error message appears consecutively, it indicates the AI is stuck in a loop, and the circuit breaker triggers.

Rate Limiting

The default limit is 100 calls/hour, preventing unexpected API billing spikes. You can adjust this via parameters:

ralph --calls 200  # Increase to 200 calls

5-Hour API Quota Three-Layer Detection

The Anthropic API has a 5-hour sliding window usage quota. frankbria includes three layers of detection:

1. Pre-check: Estimates remaining quota before each API call
2. Response detection: Parses rate limit headers from API responses
3. Fallback strategy: Automatically reduces call frequency when approaching the limit

Session Expiration Management

The default session validity is 24 hours. After that, session data is automatically cleaned up to prevent stale context from affecting subsequent executions.

Intelligent Exit Detection

frankbria doesn't simply exit when all tasks are complete. It uses a dual-condition exit gate:

Exit condition = completion_indicators >= 2 AND EXIT_SIGNAL: true

completion_indicators is the number of completion signals detected from AI output, including:

• "All tasks completed"
• "No more pending items"
• All tests passing
• All entries in fix_plan.md marked as done

EXIT_SIGNAL is an explicit exit intent declared by the AI in its output.

Why two conditions? To prevent premature exits. A single signal could be a false positive — for example, the AI might say "task complete" when it has only finished the current story. The dual condition ensures the loop only truly exits when multiple independent signals confirm completion.

Comparison with snarktank/ralph

Core Difference: Level of Engineering

Both are external bash loops launching new Claude processes. The core difference isn't in session management (frankbria can switch to fresh session mode via --no-continue), but in the level of engineering:

• snarktank: Minimalist script, a few hundred lines of bash, focused on the loop itself
• frankbria: Full-engineered toolchain — monitoring dashboard, circuit breaker, rate limiting, session expiration management

frankbria enables --continue by default to reuse sessions, which suits short tasks. For long tasks, you can switch to --no-continue mode to get the same Context Rot protection as snarktank, while retaining frankbria's engineering advantages.

How to Disable Session Reuse

frankbria offers three ways to disable --continue:

# Method 1: Command-line argument
ralph --no-continue

# Method 2: Environment variable
export CLAUDE_USE_CONTINUE=false

# Method 3: .ralphrc configuration
SESSION_CONTINUITY=false

Once disabled, frankbria behaves like snarktank (fresh session each time), but retains all engineering tools (monitoring, circuit breaker, rate limiting, etc.).

The Real-World Trade-off of Context Rot

The choice of session reuse strategy is fundamentally a trade-off between Context Rot and startup overhead:

Short tasks (< 50k tokens): Session reuse has the advantage. Context hasn't had time to degrade, and memory from earlier iterations can still benefit subsequent ones. The startup overhead of creating a new session each time is actually wasteful.

Long tasks (100k+ tokens): Fresh sessions are more reliable. Beyond 100k tokens, Context Rot intensifies significantly — accumulated context turns from an asset into a liability. Fresh sessions have startup overhead, but each one starts in optimal condition.

Practical recommendations:

frankbria users can choose flexibly based on task scale: use the default --continue mode for short tasks, and switch to --no-continue mode for long tasks. Compared to snarktank, frankbria's advantage is that the complete engineering toolchain is retained regardless of which mode is used.

Summary

frankbria/ralph-claude-code represents the engineered implementation path of the Ralph methodology. It trades some of snarktank's simplicity for more comprehensive monitoring, safety, and configuration capabilities.

Which implementation you choose depends on your specific needs — there's no "more correct" answer, only a "better fit."

Further reading:

• Ralph Wiggum Deep Dive — Core principles and methodology
• snarktank/ralph Practical Guide — Minimalist outer loop implementation
• GSD Deep Dive — A complete context engineering system built on Ralph
• Claude System Architecture Guide — Understanding the overall architecture of Hooks, Subagents, and other components