Ralph Loop

Autonomous coding agent that implements features through incremental user stories.

Ralph breaks your feature into small, testable stories, then runs Claude in a loop until all stories pass and a PR is created.

Installation

Option 1: Clone into your project

# From your project root
git clone https://github.com/ilgaribaldi/ralph-loop .ralph

Option 2: Degit (no git history)

npx degit ilgaribaldi/ralph-loop .ralph

Option 3: Manual download

Download and extract to .ralph/ in your project root.

Quick Start

1. Configure for your project

# Create config from template
cp .ralph/config/ralph.config.example.json .ralph/config/ralph.config.json

# Edit with your project's commands
# e.g., "npm test" vs "bun test" vs "cargo test"

2. Generate a PRD

Use Claude Code with the ralph-loop skill:

/ralph-loop to implement user authentication with email/password

Or manually create .ralph/runtime/prd.json from the template.

3. Run the loop

# Bash (Linux/Mac/Git Bash)
.ralph/bin/ralph.sh 25

# PowerShell (Windows)
.ralph/bin/ralph.ps1 -MaxIterations 25

# Python (cross-platform)
python .ralph/bin/ralph.py --iterations 25

4. Watch progress

# TUI dashboard
python .ralph/tui/main.py

# Or just watch the PRD
watch cat .ralph/runtime/prd.json

How It Works

1. You describe a feature - Ralph analyzes and breaks it into small stories
2. PRD is generated - Each story has acceptance criteria and priority
3. Loop runs - Claude implements one story per iteration
4. Progress tracked - Stories marked as passes: true when done
5. PR created - When all stories pass, Ralph creates a pull request

Configuration

Edit .ralph/config/ralph.config.json:

{
  "projectName": "my-project",

  "commands": {
    "typecheck": "npm run typecheck",
    "test": "npm test",
    "build": "npm run build"
  },

  "paths": {
    "projectRoot": "../..",
    "claudeMd": "../../.claude/CLAUDE.md"
  },

  "git": {
    "baseBranch": "main",
    "branchPrefix": "ralph/"
  },

  "loop": {
    "maxIterations": 25,
    "sleepBetweenIterations": 2
  }
}

Common configurations

Bun:

"commands": {
  "typecheck": "bun run typecheck",
  "test": "bun test",
  "build": "bun run build"
}

Rust:

"commands": {
  "typecheck": "cargo check",
  "test": "cargo test",
  "build": "cargo build --release"
}

Python:

"commands": {
  "typecheck": "mypy .",
  "test": "pytest",
  "build": "python -m build"
}

PRD Format

{
  "featureName": "User Authentication",
  "branchName": "ralph/user-auth",
  "baseBranch": "main",
  "description": "Add email/password authentication",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add user schema",
      "description": "Create database table for users",
      "acceptanceCriteria": [
        "Table exists with email, password_hash columns",
        "Typecheck passes",
        "Tests pass"
      ],
      "priority": 1,
      "passes": false,
      "notes": "Follow existing schema patterns"
    }
  ]
}

File Structure

your-project/
└── .ralph/                     # Ralph installation
    ├── bin/
    │   ├── ralph.sh           # Bash runner
    │   ├── ralph.ps1          # PowerShell runner
    │   └── ralph.py           # Python runner
    ├── agent/
    │   └── prompt.md          # Agent instructions
    ├── config/
    │   ├── ralph.config.json  # Your config
    │   └── prd-template.json  # PRD template
    ├── docs/
    │   └── story-patterns.md  # Story writing guide
    ├── skill/
    │   ├── SKILL.md           # Claude skill definition
    │   └── ralph-manager.md   # Setup agent
    ├── tui/
    │   └── main.py            # TUI dashboard
    └── runtime/               # Per-feature files
        ├── prd.json           # Current PRD
        └── progress.txt       # Progress log

Resuming

If the loop stops before completing:

# Check status
cat .ralph/runtime/prd.json | jq '.userStories[] | select(.passes == false)'

# Resume
.ralph/bin/ralph.sh 15

Tips

1. Small stories - Each story should be completable in one iteration
2. Clear criteria - Acceptance criteria must be specific and testable
3. Dependencies first - Lower priority = higher priority (schema before UI)
4. Always finalize - Every PRD should end with a finalization story

Cost Estimates

• Small feature (5-10 stories): ~$10-25
• Medium feature (15-20 stories): ~$30-50
• Large feature (25+ stories): ~$50-100

Claude Code API costs ~$2-5 per iteration depending on context size.

Troubleshooting

"claude command not found"

Install Claude CLI: https://github.com/anthropics/claude-code

"Config not found"

cp .ralph/config/ralph.config.example.json .ralph/config/ralph.config.json

"PRD not found"

Generate one first:

/ralph-loop to implement [your feature]

Stories keep failing

Check acceptance criteria - they may be too vague or impossible. Update the PRD and resume.

License

MIT