Ralph - Autonomous AI Development Loop for Claude Code

What is Ralph?

Claude Code Automation

⚠️

Claude Code Only

Ralph is built exclusively for Claude Code, Anthropic's official command-line interface. You must have the claude CLI installed and authenticated before using Ralph. This is not a generic AI wrapper. It's purpose-built for Claude Code's specific behavior and API patterns.

∞

The Loop Concept

Ralph wraps Claude Code in a while loop, repeatedly invoking it with your PROMPT.md file. After each execution, Ralph analyzes Claude's response to determine if the task is complete or if another iteration is needed. This continues until project objectives are met.

🔧

Prerequisites

Requires: Claude Code CLI (claude command), tmux for session management, and bash. Ralph orchestrates these tools together. It doesn't replace Claude Code, it automates the repeated invocation pattern that complex projects require.

How the Loop Works

Under the Hood

The Ralph Loop Cycle

Read Prompt

PROMPT.md

Ralph reads your project requirements from PROMPT.md file

Invoke Claude

claude --print

Executes Claude Code CLI with your prompt, capturing the response

Analyze Response

response_analyzer

Semantic analysis determines if task is complete or needs iteration

Loop or Exit

while [ ! complete ]

Continues looping until exit conditions are met

The Core Loop (Simplified)

# Ralph's core loop (simplified pseudocode)
while [ $loop_count -lt $max_calls ]; do
    
    # Invoke Claude Code CLI with your prompt
    response=$(claude --print -p "$(cat PROMPT.md)")
    
    # Log the response
    echo "$response" >> logs/ralph.log
    
    # Analyze if task is complete
    if analyze_response "$response"; then
        echo "✓ Project complete!"
        exit 0
    fi
    
    # Rate limiting check
    check_rate_limit
    
    ((loop_count++))
done

Project File Structure

my-project/
├── PROMPT.md          # Your project requirements (Ralph reads this)
├── @fix_plan.md       # Current task list for Claude to work on
├── logs/
│   └── ralph.log      # Execution logs with timestamps
├── .claude/            # Claude Code settings (created by claude init)
└── src/                # Your source code (Claude modifies this)

Intelligent Exit Detection

How Ralph Knows When to Stop

🧠

Response Analyzer

After each Claude Code execution, Ralph's response analyzer parses the output using semantic pattern matching. It looks for completion signals like "all tasks complete", "no remaining work", or explicit done markers in Claude's response.

📋

Task File Monitoring

Ralph monitors @fix_plan.md for remaining tasks. When Claude marks all items complete or the file indicates no pending work, Ralph triggers exit. This file acts as the shared state between Ralph and Claude Code.

🛑

Exit Thresholds

Configurable thresholds prevent premature or delayed exits. Ralph tracks consecutive "complete" signals, requiring multiple confirmations before stopping to avoid false positives from ambiguous responses.

⏱

Rate Limit Detection

Ralph detects Claude's API rate limits and 5-hour usage cap. When hit, it displays a countdown timer and offers options: wait for the limit to reset or gracefully exit the loop.

🔄

Circuit Breaker

After repeated failures or stuck states, the circuit breaker trips. This prevents infinite loops when Claude Code encounters errors, unresolvable conflicts, or repeatedly produces the same output.

📊

Max Iterations

Hard limit on loop iterations (default: 100 calls/hour). Even if exit detection fails, Ralph will stop at the configured maximum to prevent runaway API usage and costs.

tmux Integration

Background Execution & Monitoring

🖥️

Detachable Sessions

Ralph runs inside a tmux session, allowing you to detach (Ctrl+B D) and close your terminal while the loop continues. Reattach anytime with tmux attach to check progress.

📺

Split Pane Dashboard

The --monitor flag creates a split-pane view: one pane shows the live Ralph loop, another tails the log file. Navigate between panes with Ctrl+B ←/→.

📝

Live Log Streaming

All Claude Code interactions are logged to logs/ralph.log with timestamps. The monitor pane runs tail -f on this file, giving you real-time visibility into what Claude is doing.

tmux Session Commands

# Start Ralph with integrated monitoring dashboard
ralph --monitor

# Detach from session (Ralph keeps running)
Ctrl+B then D

# List running Ralph sessions
tmux list-sessions

# Reattach to a running session
tmux attach -t ralph-session

# Switch between panes in split view
Ctrl+B then ← or →

Getting Started

Installation & First Run

Install Claude Code

First, install Anthropic's Claude Code CLI. Visit claude.ai and follow the installation guide. Authenticate with claude login. Ralph cannot work without Claude Code installed.

Install Ralph

Clone the repository and run the installer. Ralph installs globally, adding ralph, ralph-setup, and ralph-import commands to your PATH.

Create PROMPT.md

Write your project requirements in PROMPT.md. This is what Claude Code will work from. Be specific about features, tech stack, and completion criteria.

Full Installation Steps

# 1. Prerequisites: Install Claude Code CLI (required!)
# Follow instructions at: https://claude.ai/code
claude --version        # Verify it's installed
claude login           # Authenticate with Anthropic

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

# 3. Create a new project
ralph-setup my-project
cd my-project

# 4. Edit PROMPT.md with your requirements
vim PROMPT.md

# 5. Start the autonomous loop
ralph --monitor --verbose

CLI Reference

Command Line Options

Ralph Command Options

ralph [OPTIONS]

  -h, --help          Show help message
  -c, --calls NUM     Set max calls per hour (default: 100)
  -p, --prompt FILE   Set prompt file (default: PROMPT.md)
  -s, --status        Show current status and exit
  -m, --monitor       Start with tmux session and live monitor
  -v, --verbose       Show detailed progress updates
  -t, --timeout MIN   Set Claude Code timeout (1-120 minutes)

# Project setup commands
ralph-setup project-name     # Create new Ralph project
ralph-import prd.md project  # Convert PRD to Ralph project
ralph-monitor              # Manual monitoring dashboard

Claude Code Required

Automate Your Claude Code Workflow

Ralph is purpose-built for Claude Code, Anthropic's CLI. Define your project in PROMPT.md, start the loop, and let Claude Code iteratively build until completion. No other AI tools supported.

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

Ralph Autonomous AI Development Loop for Claude Code