Autonomous AI agent loop for executing PRDs (Product Requirement Documents). Ralph uses Claude AI to implement user stories iteratively, auto-committing on completion.
Once published to PyPI, you'll be able to install Ralph with:
pip install ralphInstall directly from GitHub:
# Install latest from main branch
pip install git+https://github.com/rodionsteshenko/ralph.git
# Install from specific branch
pip install git+https://github.com/rodionsteshenko/ralph.git@branch-name
# Install from specific commit
pip install git+https://github.com/rodionsteshenko/ralph.git@commit-hashAfter installation, verify with:
ralph --version
ralph --helpFor local development with editable install:
# Clone the repository
git clone https://github.com/rodionsteshenko/ralph.git
cd ralph
# Install in editable mode
pip install -e .
# Install with development dependencies
pip install -e ".[dev]"Ralph operates on the current directory, using a .ralph/ folder to store all configuration and state.
Navigate to your project directory and initialize Ralph:
cd /path/to/your/project
ralph initThis creates a .ralph/ directory with the necessary structure.
Convert your PRD document into a structured JSON file:
# For small to medium PRDs (< 10 stories)
ralph process-prd tasks/my-feature.txt
# For large PRDs (10+ stories) - uses incremental processing
ralph build-prd tasks/large-feature.txtThe PRD will be saved to .ralph/prd.json in your current directory.
Run the autonomous loop to implement your user stories:
# Execute all stories
ralph execute
# Execute a specific phase only
ralph execute --phase 1
# Limit iterations for testing
ralph execute --max-iterations 3Check status and view progress:
# Show execution status
ralph status
# View detailed PRD progress (with auto-refresh)
ralph view
# Show summary statistics
ralph summary# Start in your project directory
cd ~/projects/my-app
# Initialize Ralph
ralph init
# Process your PRD
ralph process-prd feature-spec.txt
# Execute stories iteratively
ralph execute
# Check progress
ralph status
# View detailed progress (watch mode)
ralph viewInitialize Ralph in the current directory. Creates .ralph/ folder structure.
ralph initParse a PRD text file and convert it to .ralph/prd.json.
ralph process-prd tasks/feature.txt
# Use a different Claude model
ralph process-prd tasks/feature.txt --model claude-opus-4-5-20251101Incrementally build a large PRD (10+ stories) using tool-based batching.
ralph build-prd tasks/large-project.txt
# Specify output path (default: .ralph/prd.json)
ralph build-prd tasks/large-project.txt --output custom-prd.jsonExecute the PRD stories using the autonomous agent loop.
# Execute all remaining stories
ralph execute
# Execute specific phase only
ralph execute --phase 2
# Limit iterations (0 = unlimited)
ralph execute --max-iterations 10
# Use custom model
ralph execute --model claude-opus-4-5-20251101
# Show verbose output
ralph execute --verboseAliases: execute-plan, run
Show current Ralph status and story completion.
# Show overall status
ralph status
# Show status for specific phase
ralph status --phase 1View PRD progress with rich terminal UI (watch mode by default).
# Watch mode (auto-refresh)
ralph view
# Display once and exit
ralph view --once
# Show closed phases expanded
ralph view --expand
# Custom refresh interval (seconds)
ralph view --interval 2.0Show PRD completion statistics and metrics.
ralph summaryList stories with optional filters.
# List all stories
ralph list-stories
# Filter by phase
ralph list-stories --phase 2
# Filter by status
ralph list-stories --status incomplete
ralph list-stories --status completeMark a story as skipped (won't be executed).
ralph skip-story US-023Mark a story as in_progress.
ralph start-story US-024Show all stories currently marked as in_progress.
ralph in-progressClear stale in_progress status from stories (default: 24 hours).
# Clear stories in_progress for more than 24 hours
ralph clear-stale
# Custom age threshold
ralph clear-stale --max-age-hours 48Mark all incomplete stories in a phase as skipped.
ralph close-phase 2Validate PRD structure and story definitions.
# Basic validation
ralph validate
# Strict mode (treat warnings as errors)
ralph validate --strictInteractive story selection menu.
ralph selectRalph auto-detects your project type and configures appropriate commands automatically. No config.json needed!
Ralph detects project type based on files in your directory:
| File | Detected Type | Default Commands |
|---|---|---|
package.json |
Node | npm run typecheck, npm run lint, npm run test |
pyproject.toml |
Python | mypy ., ruff check ., pytest |
setup.py |
Python | mypy ., ruff check ., pytest |
Cargo.toml |
Rust | cargo check, cargo clippy, cargo test |
go.mod |
Go | go build, go vet, go test ./... |
Override auto-detected values with CLI flags:
# Override Claude model
ralph execute --model claude-opus-4-5-20251101
# Combine multiple overrides
ralph execute \
--model claude-opus-4-5-20251101 \
--max-iterations 5Ralph expects PRDs in a specific JSON format. Use ralph process-prd to convert text PRDs automatically.
Example PRD structure (.ralph/prd.json):
{
"project": "My Project",
"branchName": "ralph/feature-name",
"description": "Feature description",
"phases": {
"1": { "name": "Foundation", "description": "Core setup" }
},
"userStories": [
{
"id": "US-001",
"title": "Story title",
"description": "As a user, I want...",
"acceptanceCriteria": [
"Criterion 1",
"Typecheck passes"
],
"priority": 1,
"phase": 1,
"status": "incomplete",
"notes": ""
}
],
"metadata": {
"createdAt": "2026-01-19T12:00:00",
"totalStories": 1,
"completedStories": 0,
"currentIteration": 0
}
}When Ralph runs on your project, it creates this structure:
your-project/
├── .ralph/ # Ralph state (auto-created)
│ ├── prd.json # Structured PRD
│ ├── progress.md # Execution log
│ ├── guardrails.md # Learned failures
│ └── logs/ # Detailed iteration logs
├── src/ # Your project code
└── tests/ # Your tests
Ralph's internal package structure:
src/ralph/
├── __init__.py # Package initialization, version
├── cli.py # Command-line interface
├── commands.py # Command implementations
├── detect.py # Project type detection
├── prd.py # PRD parsing and management
├── loop.py # Main execution loop
├── builder.py # Incremental PRD builder
├── tools.py # PRD manipulation tools
├── viewer.py # Terminal PRD viewer
└── utils.py # Utility functions
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage
pytest --cov=src/ralph
# Run only unit tests (exclude E2E)
pytest -m "not e2e"
# Run only E2E tests
pytest -m e2e# Type checking
mypy src/ralph/
# Linting
ruff check src/ tests/
# Auto-fix linting issues
ruff check --fix src/ tests/
# Format code
ruff format src/ tests/- Python 3.9+
- Anthropic Claude API access (for agent execution)
- Git (for auto-commit functionality)
Current version: 0.1.0
MIT
Contributions welcome! Please open an issue or submit a pull request.
- GitHub Issues: https://github.com/rsteshenko/ralph/issues
- Documentation: See
CLAUDE.mdfor detailed architecture and patterns