Ralph is an autonomous development loop system that uses Claude Code to iteratively implement features from a PRD (Product Requirements Document).
To add Ralph to your existing project, copy the entire ralph directory into your repo:
cp -r path/to/ralph your-project/Or if you are starting from this repo, clone and copy:
git clone https://github.com/ky-zo/ralph.git
cp -r ralph your-project/# 1. Create a new project
./ralph/new.sh my-feature
# 2. Edit your PRD
code ralph/projects/my-feature/prd.md
# 3. Convert PRD to JSON tasks
./ralph/convert.sh my-feature
# 4. Start the loop (with tmux monitoring)
./ralph/start.sh my-feature --monitor# Install dependencies
brew install jq tmux coreutils
npm install -g @anthropic-ai/claude-codeFor browser debugging capabilities with Claude Code, add the Chrome DevTools MCP server:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latestCreate a new project from template.
./ralph/new.sh signals
# Creates: ralph/projects/signals/Convert your PRD.md to actionable JSON tasks using Claude.
./ralph/convert.sh signals
# Reads: ralph/projects/signals/prd.md
# Creates: ralph/projects/signals/prd.jsonRun the autonomous development loop.
# Without tmux (output directly in terminal)
./ralph/start.sh signals
# With tmux monitoring (recommended)
./ralph/start.sh signals --monitor
# Check status
./ralph/start.sh signals --status
# Reset circuit breaker if stuck
./ralph/start.sh signals --resetOptions:
-m, --monitor- Start with tmux session and live monitor-c, --calls NUM- Max calls per hour (default: 100)-t, --timeout MIN- Claude timeout in minutes (default: 15)-s, --status- Show project status and exit-r, --reset- Reset circuit breaker
Live status dashboard (auto-started with --monitor).
./ralph/monitor.sh signals┌─────────────────────────────────────────────────────────────────┐
│ │
│ 1. Write PRD (prd.md) │
│ Human-readable requirements document │
│ │
│ 2. Convert to JSON (prd.json) │
│ Claude breaks down PRD into actionable tasks │
│ │
│ 3. Ralph Loop │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Pick next story where passes=false │ │
│ │ ↓ │ │
│ │ Generate prompt with story + context │ │
│ │ ↓ │ │
│ │ Run Claude Code │ │
│ │ ↓ │ │
│ │ Analyze response (check status block) │ │
│ │ ↓ │ │
│ │ If story complete: mark passes=true, commit │ │
│ │ ↓ │ │
│ │ If all done: exit │ │
│ │ Else: loop back │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
The prd.json file has this structure:
{
"branchName": "ralph/feature-name",
"userStories": [
{
"id": "1.1",
"category": "functional",
"story": "Short description of what to build",
"steps": [
"Step 1: What to do",
"Step 2: Next action",
"Step 3: How to verify"
],
"acceptance": "Detailed acceptance criteria",
"priority": 1,
"passes": false,
"notes": ""
}
]
}| Field | Description |
|---|---|
branchName |
Git branch Ralph will create/use for this feature |
id |
Story identifier (phase.sequence, e.g., "1.1", "2.3") |
category |
One of: technical, functional, ui |
story |
One-sentence description of what to build |
steps |
Actionable steps to complete the story |
acceptance |
Definition of "done" |
priority |
Lower = do first (1-10 MVP, 11-20 Phase 2, 21+ Phase 3) |
passes |
Set to true when story is complete |
notes |
Ralph fills this with learnings during implementation |
When running with --monitor:
| Keys | Action |
|---|---|
Ctrl+B, D |
Detach (keeps running in background) |
Ctrl+B, ←/→ |
Switch between panes |
Ctrl+B, [ |
Enter scroll mode (q to exit) |
tmux ls |
List sessions |
tmux attach -t ralph-<project> |
Reattach to session |
- Rate Limiting: Max 100 calls/hour (configurable)
- Circuit Breaker: Auto-stops after repeated failures
- Exit Detection: Stops when Claude signals completion
- Branch Isolation: Each feature runs on its own git branch
Ralph has a two-tier learning system:
| File | Purpose | Lifetime |
|---|---|---|
progress.txt |
Session memory for Ralph | Per-project |
AGENTS.md |
Permanent docs for humans & future agents | Forever |
## Codebase Patterns
- Migrations: Use IF NOT EXISTS
- Types: Export from actions.ts
## Key Files
- db/schema.ts
- app/auth/actions.ts
---
## 2024-01-15 - Story 1.1
- What was implemented
- **Learnings:** patterns discoveredRalph updates AGENTS.md files in directories where it made changes:
✅ Good additions:
- "When modifying X, also update Y"
- "This module uses pattern Z"
- "Tests require dev server running"
❌ Don't add:
- Story-specific details
- Temporary notes
ralph/
├── new.sh # Create new project
├── convert.sh # PRD → JSON converter
├── start.sh # Main loop
├── monitor.sh # Status dashboard
├── lib/
│ ├── utils.sh
│ ├── circuit_breaker.sh
│ └── response_analyzer.sh
├── templates/
│ ├── PROMPT.md # Standard prompt
│ ├── prd-template.md # PRD template
│ └── prd-schema.json # JSON example
└── projects/
└── <your-projects>/
├── prd.md # Your PRD
├── prd.json # Generated tasks
├── progress.txt # Progress log
├── status.json # Current status
├── PROMPT.md # Standard prompt
└── logs/ # Execution logs
./ralph/start.sh <project> --status # Check what happened
./ralph/start.sh <project> --reset # Reset and continueRalph automatically waits for the next hour. You can detach with Ctrl+B, D and come back later.
Check the logs in ralph/projects/<project>/logs/ for details.
