persistent-ralph

Persistent Ralph

An autonomous agent loop for Claude Code that never stops until the task is complete.

Based on the Ralph Technique by Geoffrey Huntley, integrated as a Claude Code plugin.

Features

Problem	Solution
Claude stops after auto-compact	PreCompact hook saves state, SessionStart auto-resumes
Session ends unexpectedly	Stop hook blocks exit with decision: block
Manual restart needed	SessionStart hook injects context automatically
Context loss	Progress saved to experiments.md

Safety Features

• Circuit Breaker: Detects stagnation (5 iterations with no progress) and stops the loop
• Rate Limiter: 100 API calls/hour limit with automatic pause/resume
• Session Manager: 24-hour session expiry with auto-renewal
• Response Analyzer: Parses RALPH_STATUS blocks and detects completion signals

Installation

Option 1: Install from GitHub Marketplace

# Add the marketplace
/plugin marketplace add Lay4U/persistent-ralph

# Install the plugin
/plugin install persistent-ralph@persistent-ralph

Note: Claude Code uses SSH to clone plugins. You need SSH keys configured with GitHub. See SSH Key Setup below if you get "Permission denied (publickey)" error.

Option 2: Using --plugin-dir flag (No SSH required)

# Clone the repository
git clone https://github.com/Lay4U/persistent-ralph.git

# Run Claude Code with the plugin
claude --plugin-dir /path/to/persistent-ralph/plugins/persistent-ralph

Requirements

• Git Bash (Windows): Required for running shell scripts
• jq: JSON processor (choco install jq on Windows, brew install jq on macOS)

SSH Key Setup

Claude Code requires SSH authentication to install plugins from GitHub (related issue).

# 1. Generate SSH key (skip if you already have one)
ssh-keygen -t ed25519 -C "[email protected]"

# 2. Copy your public key
cat ~/.ssh/id_ed25519.pub

3. Add the key to GitHub: https://github.com/settings/keys
4. Test connection:

ssh -T [email protected]
# Should show: "Hi username! You've successfully authenticated..."

Usage

Quick Start

# Start a Ralph loop
/persistent-ralph:ralph-loop "Implement user authentication" --max-iterations 50

# With completion promise (loop exits when promise is fulfilled)
/persistent-ralph:ralph-loop "Fix all bugs" --completion-promise "All tests passing"

Commands

Command	Description
/persistent-ralph:ralph-loop	Start the autonomous loop
/persistent-ralph:cancel-ralph	Cancel the active loop
/persistent-ralph:setup	Initialize project structure
/persistent-ralph:import	Import PRD as specs
/persistent-ralph:help	Show help

RALPH_STATUS Block

Claude reports status at the end of each iteration:

---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: 3
FILES_MODIFIED: 5
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: Next step summary
---END_RALPH_STATUS---

Exit Conditions

The loop exits when:

1. EXIT_SIGNAL: true is reported (all tasks complete)
2. Completion promise is fulfilled (e.g., <promise>All tests passing</promise>)
3. Circuit breaker opens (5 iterations with no progress)
4. Max iterations reached
5. User cancels with /persistent-ralph:cancel-ralph

Architecture

persistent-ralph/
├── .claude-plugin/
│   └── plugin.json           # Plugin metadata
├── hooks/
│   ├── hooks.json            # Hook definitions
│   ├── stop-hook.sh          # Blocks session exit
│   ├── pre-compact.sh        # Saves state before compact
│   ├── auto-resume.sh        # Resumes on session start
│   ├── prompt-replace.sh     # Replaces empty prompts
│   ├── lib/                  # Utility libraries
│   │   ├── utils.sh
│   │   ├── circuit-breaker.sh
│   │   ├── rate-limiter.sh
│   │   ├── session-manager.sh
│   │   ├── response-analyzer.sh
│   │   └── status-generator.sh
│   └── run-*.cmd             # Windows wrappers
├── commands/
│   ├── ralph-loop.md         # Start loop command
│   ├── cancel-ralph.md       # Cancel loop command
│   ├── setup.md              # Project setup
│   ├── import.md             # Import PRD
│   └── help.md               # Help documentation
└── templates/
    ├── PROMPT.md             # Project prompt template
    ├── fix_plan.md           # Task list template
    └── AGENT.md              # Build instructions template

State Files