Ralph - Autonomous AI Agent Loop for Claude Code

An autonomous AI agent loop that runs Claude Code repeatedly until all tasks are complete. Each iteration is a fresh Claude Code instance with clean context.

This fork adds:

• agent-browser integration for automated UI testing and screenshot verification
• Archive system for preserving history across PRD changes
• AGENTS.md pattern for capturing reusable knowledge per directory
• Codebase Patterns section for consolidated learnings

Based on Geoffrey Huntley's Ralph pattern and snarktank/ralph.

---

Quick Start

# 1. Set up Ralph in your project
cd your-project
mkdir -p scripts/ralph
cd scripts/ralph
ln -s /path/to/ralph/claude-code/ralph.sh ralph.sh
ln -s /path/to/ralph/claude-code/prompt.md prompt.md

# 2. Create your PRD (or ask Claude Code to help)
# See prd.json.example for format

# 3. Run Ralph
./ralph.sh 10  # Run up to 10 iterations

---

Features

Core Loop

• Runs Claude Code in fresh context windows per iteration
• Picks highest priority story with passes: false
• Commits changes with standardized messages
• Detects completion via <promise>COMPLETE</promise> marker

agent-browser Integration

Automated browser testing for frontend stories:

agent-browser open http://localhost:3000
agent-browser snapshot -i              # Get interactive elements (@e1, @e2)
agent-browser click @e1                # Click element
agent-browser fill @e2 "test value"   # Fill input
agent-browser screenshot proof.png     # Capture proof

Archive System

Automatically archives previous PRD runs when switching to a new branch:

scripts/ralph/archive/
  2024-01-15-feature-login/
    prd.json
    progress.txt

Knowledge Persistence

• progress.txt: Iteration logs with learnings
• Codebase Patterns: Consolidated reusable patterns at top of progress.txt
• AGENTS.md: Directory-specific knowledge for future iterations

---

File Structure

ralph/
├── claude-code/           # Core Ralph files (symlink targets)
│   ├── ralph.sh           # Main loop script
│   ├── prompt.md          # Agent instructions
│   ├── settings.json      # Claude Code permissions config
│   ├── prd.json.example   # PRD template
│   ├── project-README.md  # README template for projects
│   ├── screenshots/       # Screenshot storage
│   ├── commands/
│   │   └── create-prd.md  # Guided PRD creation command
│   └── skills/
│       └── agent-browser/ # Browser automation skill
├── USAGE-GUIDE.md         # Comprehensive documentation
└── README.md              # This file

In Your Project

your-project/
└── scripts/ralph/
    ├── ralph.sh      → symlink to claude-code/ralph.sh
    ├── prompt.md     → symlink to claude-code/prompt.md
    ├── prd.json      # Your tasks (local)
    ├── progress.txt  # Iteration logs (local)
    ├── screenshots/  # UI verification screenshots
    └── README.md     # Project-specific docs

---

PRD Format

{
  "project": "ProjectName",
  "branchName": "ralph/feature-name",
  "description": "What this PRD accomplishes",

  "nonGoals": [
    "Explicit scope boundary",
    "Things NOT included in this PRD"
  ],

  "relevantFiles": [
    { "path": "src/Component.tsx", "action": "create", "purpose": "Main component" },
    { "path": "src/api/endpoint.ts", "action": "modify", "purpose": "Add new route" }
  ],

  "userStories": [
    {
      "id": "US-001",
      "title": "Short task title",
      "description": "As a [user], I want [what] so that [why].",
      "subtasks": [
        "First granular step",
        "Second granular step",
        "Third granular step"
      ],
      "acceptanceCriteria": [
        "Specific verifiable criterion",
        "npm run lint passes",
        "npx tsc --noEmit succeeds"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

PRD Schema

Field	Description
nonGoals	Explicit scope boundaries - prevents scope creep
relevantFiles	Files to create/modify with purpose - helps scope work
subtasks	Granular steps within each story - more trackable

Tips for Good Stories

• Keep them small: Each story should complete in one iteration
• Use subtasks: Break complex stories into granular steps
• Be specific: Clear acceptance criteria prevent ambiguity
• Include quality checks: Always require lint/typecheck to pass
• Order by priority: Ralph picks the highest priority incomplete story
• Define non-goals: Explicitly state what's out of scope

---

Claude Code Configuration

Pre-configured Permissions (settings.json)

Copy to your project's .claude/settings.json for auto-allowed commands:

mkdir -p .claude
cp /path/to/ralph/claude-code/settings.json .claude/

Allowed by default:

• Web fetching
• agent-browser commands
• npm/pnpm/yarn/bun commands
• Python/pip/pytest
• Git operations (diff, status, log, add, commit, branch, checkout)
• File operations (cat, ls, mkdir, cp, mv, grep, find, jq)

Blocked:

• sudo, docker, rm -rf
• Reading .env files, SSH keys, AWS credentials

Requires confirmation:

• git push

/create-prd Command

Guided PRD creation with lettered options for quick responses:

/create-prd

The command uses an 8-phase workflow:

1. Discovery Questions - Lettered options (respond "1A, 2C, 3B")
2. Research - If needed, helps with tech choices
3. Parent Tasks - Generate high-level tasks, get approval
4. Sub-Tasks - Expand into granular steps after "Go"
5. Full PRD - Generate complete prd.json with nonGoals, relevantFiles
6. Review - Verify scope and stories with user
7. Write Files - Save prd.json and initialize progress.txt
8. Instructions - How to run Ralph

Inspired by snarktank/ai-dev-tasks methodology.

---

Requirements

• Claude Code CLI
• Node.js (for agent-browser)
• jq (for JSON parsing in shell)

Installing agent-browser

npm install -g agent-browser
agent-browser install  # Download Chromium

---

Usage

Running Ralph

cd your-project
./scripts/ralph/ralph.sh [max_iterations]

Default is 10 iterations. Set higher than your story count to allow retries.

Creating a PRD with Claude Code

I want to add [feature description] to my project.
Help me create a prd.json for Ralph.
Ask me clarifying questions first, then create the prd.json.

Checking Status

cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

---

Credits

• Original concept: Geoffrey Huntley
• Base implementation: snarktank/ralph
• PRD workflow: snarktank/ai-dev-tasks
• agent-browser inspiration: coleam00/ralph-loop-quickstart
• agent-browser tool: Vercel Labs