Ralph Loop

Autonomous agent loop for Claude Code and OpenCode.

Installation

$3

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

Then run from any directory:

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

$3

`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 | Generate a new prd.json from a prompt |
| get-story | Get the current story to work on |
| mark-complete | Mark a user story as complete |

Run Options

| Option | Description | Default |
|--------|-------------|---------|
| -a, --agent | Agent to use (claude or opencode) | claude |
| -i, --max-iterations | Maximum iterations | 10 |
| -t, --max-tokens | Maximum token budget | unlimited |
| -p, --prompt | Path to prompt template | built-in |
| --prd | Path to prd.json | ./prd.json |
| --progress | 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 | Iterations on same story before declaring stuck | 5 |
| --verify-command | Command to run before mark-complete succeeds | none |
| --context-size | 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 COMPLETE
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:

$3

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

$3

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

$3

`markdown


Phase 0: Orientation

$3

You are working on {{project}}...

$3

{{stories}}

Phase 1-4: Workflow

$3

- Review the codebase...

Phase 99999: Critical Guardrails

$3

- This rule is critical...
``