ralph-cli 2.2.0

A Python CLI tool that implements the Ralph autonomous iteration pattern for Claude Code

Ralph CLI

A Python CLI tool that implements the Ralph autonomous iteration pattern for Claude Code. Ralph enables AI-driven development by breaking down specifications into user stories and executing them autonomously.

Features

• Project Scaffolding: Initialize any project with Ralph workflow files
• PRD Generation: Create product requirements documents interactively with Claude
• Task Breakdown: Convert specifications into structured user stories
• Autonomous Iteration: Execute stories one at a time with quality checks
• Loop Execution: Run multiple iterations automatically with failure detection
• Skills Management: Sync custom Claude Code skills to your system
• Code Review Skills: Built-in reviewers for Python, repo structure, GitHub Actions, and tests

Installation

Requires Python 3.11+ and uv package manager.

# Clone the repository
git clone https://github.com/jackemcpherson/ralph-cli.git
cd ralph-cli

# Install with dev dependencies
uv pip install -e ".[dev]"

# Verify installation
ralph --version

Quick Start

# 1. Initialize Ralph in your project
cd your-project
ralph init

# 2. Create a PRD interactively
ralph prd

# 3. Convert the PRD to tasks
ralph tasks plans/SPEC.md

# 4. Run autonomous iterations
ralph loop

Commands

Command	Description
ralph init	Scaffold a project for Ralph workflow
ralph prd	Create a PRD interactively with Claude
ralph tasks <spec>	Convert spec to TASKS.json
ralph once	Execute single iteration
ralph loop [n]	Run n iterations (default: 10)
ralph review	Run the review pipeline with automatic configuration
ralph sync	Sync skills to ~/.claude/skills/

ralph init

Scaffolds your project with Ralph workflow files:

ralph init                    # Auto-detect project type
ralph init --name MyProject   # Custom project name
ralph init --skip-claude      # Skip Claude Code enhancement
ralph init --force            # Overwrite existing files

If no PRD exists at plans/SPEC.md, you'll be prompted to create one interactively before proceeding.

Creates:

• plans/SPEC.md - Specification template
• plans/TASKS.json - Task list (empty)
• plans/PROGRESS.txt - Progress log
• CLAUDE.md - Project instructions with quality checks
• AGENTS.md - Agent workflow instructions

ralph prd

Launches an interactive session with Claude to create a PRD:

ralph prd                     # Output to plans/SPEC.md
ralph prd --output custom.md  # Custom output path
ralph prd --verbose           # Verbose Claude output

ralph tasks

Converts a specification file to structured tasks:

ralph tasks plans/SPEC.md              # Default output
ralph tasks spec.md --output tasks.json # Custom output
ralph tasks spec.md --branch feature/x  # Custom branch name

ralph once

Executes a single iteration (one user story):

ralph once                      # Run one iteration
ralph once --verbose            # Show full Claude output
ralph once --max-fix-attempts 5 # Custom retry limit

ralph loop

Runs multiple iterations automatically:

ralph loop                      # Run up to 10 iterations
ralph loop 5                    # Run up to 5 iterations
ralph loop --verbose            # Verbose output
ralph loop --max-fix-attempts 5 # Custom retry limit per story

Stop conditions:

• All stories complete
• Max iterations reached
• Persistent failure (same story fails twice)
• Transient failure (Claude error)

ralph review

Runs the automated review pipeline:

ralph review                    # Auto-detect and configure reviewers
ralph review --force            # Re-detect and overwrite reviewer config
ralph review --strict           # Treat warnings as blocking
ralph review --verbose          # Verbose Claude output

On first run, detects project languages and configures reviewers in CLAUDE.md. On subsequent runs, uses the existing configuration and suggests any missing reviewers.

ralph sync

Syncs skills to Claude Code:

ralph sync                           # Sync from ./skills
ralph sync --skills-dir /path/to/skills  # Custom source
ralph sync --remove                  # Remove synced skills

Reviewer Skills

Ralph includes code review skills that can be invoked directly in Claude Code:

Skill	Description
/python-code-reviewer	Type hints, docstrings, logging, code quality
/bicep-reviewer	Azure Bicep template best practices and security
/repo-structure-reviewer	README, .gitignore, project organization
/github-actions-reviewer	CI/CD completeness, security, best practices
/test-quality-reviewer	Meaningful assertions, coverage, anti-patterns
/code-simplifier	Code clarity and maintainability improvements
/release-reviewer	Version consistency, changelog, release readiness

Each reviewer outputs a structured report with severity levels (error/warning/suggestion) and a verdict tag:

• <ralph-review>PASS</ralph-review> - No blocking errors
• <ralph-review>NEEDS_WORK</ralph-review> - Has errors that must be fixed

Project Structure

After running ralph init:

your-project/
├── CLAUDE.md           # Project instructions + quality checks
├── AGENTS.md           # Agent workflow instructions
└── plans/
    ├── SPEC.md         # Product specification
    ├── TASKS.json      # User stories with status
    └── PROGRESS.txt    # Iteration log

TASKS.json Format

{
  "project": "ProjectName",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "As a user, I want...",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Quality Checks

Define quality checks in CLAUDE.md:

<!-- RALPH:CHECKS:START -->
```yaml
checks:
  - name: typecheck
    command: uv run pyright
    required: true
  - name: lint
    command: uv run ruff check .
    required: true
  - name: test
    command: uv run pytest
    required: true

## Development

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run type checking
uv run pyright

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.