ralph-installer

Install Ralph loop files and skills for Claude Code.

Installation

Quick install (recommended)

npx ralph-installer@latest install

Install as dev dependency

npm install -D ralph-installer
npx ralph-installer install

Global install

npm install -g ralph-installer
ralph-installer install

What it installs

1. Skills - Markdown skill files installed to .claude/skills/<skill-name>/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

start / run - Interactive CLI (recommended)

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

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

install - Install skills and ralph files

ralph-installer install [options]

Options: | Option | Description | Default | |--------|-------------|---------| | --project <path> | Target project directory | Current directory | | --ralph-dir <path> | 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:

# 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

view - Launch PRD viewer

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

ralph-installer view [options]

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

Requirements: Python 3

Example:

# 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

schedule - Run Ralph with usage-aware scheduling

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

ralph-installer schedule [options]

Options: | Option | Description | Default | |--------|-------------|---------| | --ralph-dir <path> | Path to ralph directory | ralph | | --wait-next-session | Wait for next 5-hour session before starting | - | | --max-usage <percent> | Stop when block usage reaches this % (0 = no limit) | 0 | | --max-iterations <num> | Maximum iterations | 10 | | --wait | Wait for next block if usage is too high during run | - | | --wait-threshold <percent> | Start waiting when usage exceeds this % | 90 | | --check-interval <seconds> | 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:

# 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

usage - Show current Claude Code usage

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

ralph-installer usage [options]

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

Example:

# 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:

Basic loop (ralph-claude.sh)

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 <promise>COMPLETE</promise> is output
• Archives previous runs when switching branches

Usage-aware loop (scheduled-ralph.sh)

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

Or use the CLI wrapper:

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 <percent>     Stop at this usage % (0 = no limit, default: 0)
--wait                    Wait for next block if usage is high during run
--wait-threshold <pct>    Wait threshold % (default: 90)
--check-interval <sec>    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:

{
  "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:

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