ralph-installer

Install Ralph loop files and skills for Claude Code.

Installation

$3

``bash
npx ralph-installer@latest install
`

$3

`bash
npm install -D ralph-installer
npx ralph-installer install
`

$3

`bash
npm install -g ralph-installer
ralph-installer install
`

What it installs

1. Skills - Markdown skill files installed to .claude/skills//SKILL.md
- prd - Generate Product Requirements Documents
- ralph - Convert PRDs to ralph's prd.json format

2. Ralph loop files - Autonomous agent loop files to ralph/:
- prd.json - PRD in JSON format for the agent
- prompt.md - Agent instructions
- progress.txt - Progress tracking
- ralph-claude.sh - Loop runner for Claude Code CLI
- scheduled-ralph.sh - Usage-aware loop runner with scheduling

Project structure after install

`
your-project/
├── .claude/
│ └── skills/
│ ├── prd/
│ │ └── SKILL.md
│ └── ralph/
│ └── SKILL.md
└── ralph/
├── prd.json
├── progress.txt
├── prompt.md
├── ralph-claude.sh
└── scheduled-ralph.sh
`

CLI Commands

$3

Launch an interactive menu to start Ralph, view PRD, or check usage.

`bash
npx ralph-installer@latest start


or

npx ralph-installer@latest run

or just

npx ralph-installer@latest
`

Features:
- Select between Basic or Scheduled mode
- Configure iterations, usage limits, and cost limits interactively
- Quick access to PRD viewer and usage stats
- Confirmation before starting

Example session:
`
╭─────────────────────────────────╮
│ │
│ 🤖 Ralph - Autonomous Agent │
│ │
╰─────────────────────────────────╯

? Select mode ›
❯ 🚀 Basic - Run ralph-claude.sh with simple iteration limit
📊 Scheduled - Run with usage tracking and limits
👁️ View PRD - Open the PRD viewer in browser
📈 Check Usage - Show current Claude Code usage
`

$3

`bash
ralph-installer install [options]
`

Options:
| Option | Description | Default |
|--------|-------------|---------|
| --project | Target project directory | Current directory |
| --ralph-dir | Where to copy ralph/ template | ralph |
| --skills-only | Only install skills, skip ralph loop files | - |
| --ralph-only | Only copy ralph loop files, skip skills | - |
| --force | Overwrite existing files | - |
| --dry-run | Print planned operations without writing | - |
| --json | Output in JSON format for CI | - |
| --no-claude | Skip .claude/skills installation | - |

Examples:

`bash


Install everything to current directory

npx ralph-installer@latest install

Preview what will be created

npx ralph-installer@latest install --dry-run

Install only skills (no ralph loop files)

npx ralph-installer@latest install --skills-only

Install to a different project

npx ralph-installer@latest install --project /path/to/my/project

Install ralph files to a custom location

npx ralph-installer@latest install --ralph-dir scripts/ralph

Overwrite existing files

npx ralph-installer@latest install --force
`

$3

Opens a web-based PRD viewer to visualize user stories, track progress, and see dependencies.

`bash
ralph-installer view [options]
`

Options:
| Option | Description | Default |
|--------|-------------|---------|
| --ralph-dir | Path to ralph directory | ralph |
| --port | Port to use | 8089 |
| --no-open | Don't open browser automatically | - |

Requirements: Python 3

Example:

`bash


Open PRD viewer in browser

npx ralph-installer@latest view

Use custom port

npx ralph-installer@latest view --port 3000
`

Features:
- Canvas-based visualization with drag/zoom
- Dependency graph showing story relationships
- Real-time updates (auto-refresh every 2s)
- Sound notifications when story status changes
- Modal with full details including acceptance criteria
- Toggle between dependency and priority layouts

$3

Runs the Ralph loop while monitoring Claude Code usage limits using the OAuth API.

`bash
ralph-installer schedule [options]
`

Options:
| Option | Description | Default |
|--------|-------------|---------|
| --ralph-dir | Path to ralph directory | ralph |
| --wait-next-session | Wait for next 5-hour session before starting | - |
| --max-usage | Stop when block usage reaches this % (0 = no limit) | 0 |
| --max-iterations | Maximum iterations | 10 |
| --wait | Wait for next block if usage is too high during run | - |
| --wait-threshold | Start waiting when usage exceeds this % | 90 |
| --check-interval | How often to check usage when waiting | 300 |
| --dry-run | Show what would happen without running | - |
| --quiet | Suppress progress messages | - |
| --status | Just show current usage status and exit | - |

Note: Usage percentage is retrieved directly from Claude Code's OAuth API. Make sure you're logged in (claude /login).

Examples:

`bash


Run 10 iterations with no limits (default)

npx ralph-installer@latest schedule

Schedule to start at next session (5-hour block)

npx ralph-installer@latest schedule --wait-next-session

Stop at 70% usage

npx ralph-installer@latest schedule --max-usage 70

Stop at 80% usage, wait for next block if exceeded

npx ralph-installer@latest schedule --max-usage 80 --wait

Preview what would happen

npx ralph-installer@latest schedule --dry-run
`

$3

Displays your current 5-hour and 7-day usage from Claude Code's OAuth API.

`bash
ralph-installer usage [options]
`

Options:
| Option | Description |
|--------|-------------|
| --json | Output in JSON format |

Example:

`bash


Show current usage status

npx ralph-installer@latest usage

Get JSON output

npx ralph-installer@latest usage --json
`

Running the Ralph loop

After installation, you have two ways to run the autonomous agent loop:

$3

`bash
cd your-project
./ralph/ralph-claude.sh [max_iterations]
`

Requirements: Claude Code CLI (npm i -g @anthropic-ai/claude-code)

Options:
- max_iterations - Maximum iterations before stopping (default: 10)

Behavior:
- Reads instructions from ralph/prompt.md
- Tracks progress in ralph/progress.txt
- Uses ralph/prd.json for the PRD specification
- Stops when COMPLETE is output
- Archives previous runs when switching branches

$3

`bash
cd your-project
./ralph/scheduled-ralph.sh [options] [max_iterations]
`

Or use the CLI wrapper:

`bash
ralph-installer schedule --max-usage 80 --max-iterations 5
`

Requirements:
- Claude Code CLI (npm i -g @anthropic-ai/claude-code)
- jq (for JSON parsing)
- curl (for API calls)

Options:
`
--wait-next-session Wait for next 5-hour session before starting
--max-usage Stop at this usage % (0 = no limit, default: 0)
--wait Wait for next block if usage is high during run
--wait-threshold Wait threshold % (default: 90)
--check-interval Check interval when waiting (default: 300)
--dry-run Preview without running
--quiet Suppress output
--help Show help
`

Note: Usage percentage is fetched directly from Claude Code's OAuth API. Make sure you're logged in (claude /login).

PRD format (prd.json)

The ralph/prd.json file contains your product requirements:

`json
{
"project": "My Project",
"branchName": "feature/my-feature",
"description": "Project description",
"userStories": [
{
"id": "US-001",
"title": "User story title",
"description": "Detailed description",
"acceptanceCriteria": [
"Criterion 1",
"Criterion 2"
],
"priority": 1,
"passes": false,
"notes": "Implementation notes",
"dependsOn": []
},
{
"id": "US-002",
"title": "Another story",
"description": "This depends on US-001",
"acceptanceCriteria": ["..."],
"priority": 2,
"passes": false,
"notes": "",
"dependsOn": ["US-001"]
}
]
}
`

Fields:
- id - Unique identifier (e.g., "US-001")
- title - Short title
- description - Full description
- acceptanceCriteria - Array of acceptance criteria strings
- priority - Priority level (1 = highest)
- passes - Whether the story is complete (true/false)
- notes - Implementation notes
- dependsOn - Array of story IDs this depends on

Uninstall

To remove installed files:

`bash
rm -rf .claude/skills/prd .claude/skills/ralph
rm -rf ralph/
`

Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Unexpected error |
| 2` | User error (conflicts, missing path, etc.) |

License

MIT