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.
Sign in to like and favorite skills
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:
Based on Geoffrey Huntley's Ralph pattern and snarktank/ralph.
# 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
passes: false<promise>COMPLETE</promise>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
Automatically archives previous PRD runs when switching to a new branch:
scripts/ralph/archive/ 2024-01-15-feature-login/ prd.json progress.txt
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
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
{ "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": "" } ] }
| Field | Description |
|---|---|
| Explicit scope boundaries - prevents scope creep |
| Files to create/modify with purpose - helps scope work |
| Granular steps within each story - more trackable |
Copy to your project's
.claude/settings.jsonmkdir -p .claude cp /path/to/ralph/claude-code/settings.json .claude/
Allowed by default:
Blocked:
Requires confirmation:
Guided PRD creation with lettered options for quick responses:
/create-prd
The command uses an 8-phase workflow:
Inspired by snarktank/ai-dev-tasks methodology.
jqnpm install -g agent-browser agent-browser install # Download Chromium
cd your-project ./scripts/ralph/ralph.sh [max_iterations]
Default is 10 iterations. Set higher than your story count to allow retries.
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.
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'