An autonomous AI agent loop runner for Claude Code or Codex.

ralph repeatedly runs the selected coding agent to complete user stories from a PRD (Product Requirements Document), enabling autonomous multi-step development workflows.

# Make executable
chmod +x ralph

# Option 1: Run from current directory
./ralph help

# Option 2: Add to PATH for global access
sudo cp ralph /usr/local/bin/

• Bash shell
• One supported agent CLI installed and authenticated:
  • Claude Code CLI
  • OpenAI Codex CLI
• jq for JSON parsing

# Initialize ralph in your project
ralph init

# Edit the PRD with your user stories
$EDITOR prd.json

# Run the agent loop
ralph run

# Run the agent loop with Codex
ralph run --tool codex

ralph <command> [options]

COMMANDS
    run [options]      Run the agent loop
    init [dir]         Initialize ralph files in a directory (default: current dir)
    version            Show version information
    help               Show this help message

RUN OPTIONS
    -m, --max <n>      Maximum iterations (default: 10)
    -t, --tool <name>  Agent tool to run: claude | codex (default: claude)
    --dry-run          Show what would be executed without running

# Initialize in current directory
ralph init

# Initialize in a specific directory
ralph init ./my-project

# Run the agent loop
ralph run

# Run with Codex
ralph run --tool codex

# Run with up to 20 iterations
ralph run --max 20

# Preview configuration without running
ralph run --dry-run

1. ralph init creates the required files in your project directory
2. You edit prd.json to define your user stories with acceptance criteria
3. ralph run selects the prompt file for the chosen tool:
   • CLAUDE.md for --tool claude
   • CODEX.md for --tool codex
4. Ralph runs the selected CLI in non-interactive mode
5. The agent picks the highest priority incomplete story and implements it
6. The agent marks the story as complete and outputs <promise>COMPLETE</promise>
7. ralph checks for the completion signal and stops, or continues to the next iteration

The loop continues until:

• All user stories in prd.json are marked as complete
• Maximum iterations are reached (default: 10)
• You press Ctrl+C

The prd.json file defines your project and user stories:

{
  "project": "My Feature",
  "branchName": "ralph/my-feature",
  "description": "Description of the feature being built",
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "Detailed description of what needs to be done",
      "acceptanceCriteria": [
        "First acceptance criterion",
        "Second acceptance criterion"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Fields:

• priority - Lower numbers are higher priority (1 = highest)
• passes - Set to true by the agent when the story is complete
• notes - Optional field for additional context

ralph tracks the current branch from prd.json and automatically archives previous runs when the branch changes:

• Archives are stored in archive/YYYY-MM-DD-branch-name/
• Previous prd.json and progress.txt are preserved
• progress.txt is reset for the new branch

• Feature Development - Break features into user stories and let ralph implement them
• Migrations - Define migration steps as stories with acceptance criteria
• Refactoring - Create stories for each refactoring task with quality checks
• Bug Fixes - Document bugs as stories with reproduction and fix criteria

MIT