Install Ralph loop files and skills for Claude Code
npm install ralph-installerInstall Ralph loop files and skills for Claude Code.
``bash`
npx ralph-installer@latest install
`bash`
npm install -D ralph-installer
npx ralph-installer install
`bash`
npm install -g ralph-installer
ralph-installer install
1. Skills - Markdown skill files installed to .claude/skills/prd
- - Generate Product Requirements Documentsralph
- - 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 agentprompt.md
- - Agent instructionsprogress.txt
- - Progress trackingralph-claude.sh
- - Loop runner for Claude Code CLIscheduled-ralph.sh
- - Usage-aware loop runner with scheduling
``
your-project/
├── .claude/
│ └── skills/
│ ├── prd/
│ │ └── SKILL.md
│ └── ralph/
│ └── SKILL.md
└── ralph/
├── prd.json
├── progress.txt
├── prompt.md
├── ralph-claude.sh
└── scheduled-ralph.sh
Launch an interactive menu to start Ralph, view PRD, or check usage.
`bash`
npx ralph-installer@latest startor
npx ralph-installer@latest runor 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
`
`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:
`bashInstall everything to current directory
npx ralph-installer@latest install
$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 viewUse 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 scheduleSchedule to start at next session (5-hour block)
npx ralph-installer@latest schedule --wait-next-sessionStop at 70% usage
npx ralph-installer@latest schedule --max-usage 70Stop at 80% usage, wait for next block if exceeded
npx ralph-installer@latest schedule --max-usage 80 --waitPreview 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 usageGet 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 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 onUninstall
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.) |MIT