npm package: @meditatingsloth/ralph-loop
Description: Ralph Wiggum autonomous agent loop - TypeScript implementation
Author: Austin Borden
Latest version: 0.4.1

# Ralph Loop

Autonomous agent loop for Claude Code and OpenCode.

## Installation

### Global (recommended)

```bash
npm install -g @meditatingsloth/ralph-loop
```

Then run from any directory:

```bash
ralph-loop --max-iterations 5 --max-tokens 500000
```

### From source

```bash
git clone https://github.com/meditatingsloth/ralph-loop.git
cd ralph-loop
npm install
npm run build
npm link  # makes 'ralph-loop' available globally
```

## Usage

```bash
# Claude Code (default)
ralph-loop --max-iterations 5 --max-tokens 500000

# OpenCode
ralph-loop --agent opencode --max-iterations 10

# With custom paths
ralph-loop --prd ./my-prd.json --prompt ./my-prompt.md

# Dry run (show what would execute)
ralph-loop --dry-run --verbose

# Generate a new prd.json from a prompt
ralph-loop new "Build a todo app with CRUD operations"

# Get the current story to work on
ralph-loop get-story
ralph-loop get-story --json

# Mark a story as complete (with optional verification)
ralph-loop mark-complete US-001
ralph-loop mark-complete US-001 --verify-command "npm test"
```

## Commands

| Command | Description |
|---------|-------------|
| `run` (default) | Run the autonomous agent loop |
| `new <prompt>` | Generate a new prd.json from a prompt |
| `get-story` | Get the current story to work on |
| `mark-complete <storyId>` | Mark a user story as complete |

## Run Options

| Option | Description | Default |
|--------|-------------|---------|
| `-a, --agent <type>` | Agent to use (claude or opencode) | claude |
| `-i, --max-iterations <n>` | Maximum iterations | 10 |
| `-t, --max-tokens <n>` | Maximum token budget | unlimited |
| `-p, --prompt <path>` | Path to prompt template | built-in |
| `--prd <path>` | Path to prd.json | ./prd.json |
| `--progress <path>` | Path to progress.txt | ./progress.txt |
| `-v, --verbose` | Verbose output | false |
| `--dry-run` | Show what would execute | false |
| `-s, --stream` | Stream agent output to terminal | false |
| `--auto-commit` | Auto-commit code changes after completing stories (excludes prd.json/progress.txt) | false |
| `--stuck-threshold <n>` | Iterations on same story before declaring stuck | 5 |
| `--verify-command <cmd>` | Command to run before mark-complete succeeds | none |
| `--context-size <n>` | Context window size override | agent-specific |

## PRD Format

```json
{
  "project": "my-project",
  "branchName": "feature/xyz",
  "baseContext": "Tech stack: React + TypeScript. Use existing utils in src/lib/.",
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "What needs to be done",
      "passes": false,
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "priority": 1
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `project` | Project name |
| `branchName` | Git branch name for this work |
| `baseContext` | (optional) Shared context included in every story's prompt |
| `userStories` | Array of user stories |

## Termination Conditions

The loop terminates when any of these occur:
1. All stories have `passes: true`
2. Max iterations reached
3. Max tokens exceeded
4. Agent outputs `<promise>COMPLETE</promise>`
5. Agent is stuck on the same story (exceeds `--stuck-threshold`)
6. Context utilization exceeds 75%

## Prompt Template Phase Structure

The default prompt template uses a phased structure with numbered sections. When creating custom prompts, follow this pattern:

### Phase Numbers

| Phase | Purpose | Description |
|-------|---------|-------------|
| 0a-0d | Orientation | Context, current state, progress history, goals |
| 1-4 | Workflow | Analyze → Implement → Verify → Complete |
| 99999+ | Critical Guardrails | Rules that override all other instructions |

### Phase Structure Rationale

- **Lower numbers = orientation** (what the agent needs to know)
- **Middle numbers = workflow** (what the agent should do)
- **High numbers = critical constraints** (rules that must not be violated)

The high priority numbers (99999+) for guardrails signal to the agent that these rules take precedence over everything else.

### Example Custom Prompt

```markdown
## Phase 0: Orientation
### 0a. Context
You are working on {{project}}...

### 0b. Current State
{{stories}}

## Phase 1-4: Workflow
### Phase 1: Analyze
- Review the codebase...

## Phase 99999: Critical Guardrails
### 99999.1: YOUR CUSTOM RULE
- This rule is critical...
```