Ralph Loop

Autonomous agent loop for Claude Code and OpenCode.

Installation

Global (recommended)

npm install -g @meditatingsloth/ralph-loop

Then run from any directory:

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

From source

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

# 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

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

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