ralph-mode

Initialize Ralph Wiggum autonomous AI coding loops in any project.

Ralph runs your AI coding CLI (Claude Code, Amp, OpenCode) in a loop, letting it work autonomously on a list of tasks. You define what needs to be done. Ralph figures out how.

Features

• Multi-CLI Support - Works with Claude Code, Amp, and OpenCode
• PRD Import - Convert existing requirements to Ralph format with AI
• Circuit Breaker - Automatically stops runaway loops
• Docker Sandbox - Optional isolation for AFK safety
• AGENTS.md - Persistent project conventions and learnings
• Progress Tracking - Accumulated learnings across iterations
• Configurable - Customize CLI, limits, feedback loops

Installation

Quick Install (Recommended)

curl -fsSL https://gitlab.com/jcappel/ralph-mode/-/raw/main/install.sh | bash

Via npm/bun

npm install -g ralph-mode
# or
bun install -g ralph-mode
# or run without installing
npx ralph-mode init

Manual

git clone https://gitlab.com/jcappel/ralph-mode.git ~/.ralph-mode
ln -s ~/.ralph-mode/bin/ralph-mode ~/.local/bin/ralph-mode

Uninstall

# If installed via curl
curl -fsSL https://gitlab.com/jcappel/ralph-mode/-/raw/main/uninstall.sh | bash

# If installed via npm
npm uninstall -g ralph-mode

Quick Start

# In any project directory
ralph-mode init

# Option A: Import existing requirements
ralph-mode import requirements.md
# Review and adjust prd.json

# Option B: Create PRD manually
cp .ralph/prd.json.example prd.json
vim prd.json

# Verify setup
ralph-mode check

# Run single iteration (HITL - watch and learn)
ralph-mode once

# Run multiple iterations (AFK)
ralph-mode run 10

What Gets Created

your-project/
├── scripts/ralph/
│   ├── ralph-local.sh    # AFK multi-iteration loop
│   ├── ralph-once.sh     # HITL single iteration
│   └── check-setup.sh    # Verify prerequisites
├── .ralph/
│   ├── prompt.md         # Agent instructions (customize!)
│   ├── config.sh         # CLI & execution settings
│   ├── prd.json.example  # PRD template
│   ├── AGENTS.md.example # Project conventions template
│   └── archive/          # Completed sprint archives
├── prd.json              # Your sprint stories (you create this)
├── progress.txt          # Auto-created on first run
└── AGENTS.md             # Project conventions (optional)

Commands

| Command | Description | |---------|-------------| | ralph-mode init | Initialize Ralph in current directory | | ralph-mode init --force | Reinitialize, overwriting existing files | | ralph-mode import <file> | Convert requirements to PRD format | | ralph-mode check | Run the setup checker | | ralph-mode once | Run single HITL iteration | | ralph-mode run [N] | Run N iterations AFK (default: 10) | | ralph-mode status | Show current PRD progress | | ralph-mode help | Show help |

Configuration

Edit .ralph/config.sh to customize:

# AI CLI: claude | amp | opencode | auto
RALPH_CLI="auto"

# Execution limits
MAX_ITERATIONS=25
MAX_CONSECUTIVE_ERRORS=3
MAX_NO_PROGRESS_ITERATIONS=5

# Feedback loops (commands to run before commit)
FEEDBACK_TYPECHECK="pnpm check-types"
FEEDBACK_LINT="pnpm lint"
FEEDBACK_TEST="pnpm test"

# Docker sandbox (requires Docker Desktop 4.50+)
USE_DOCKER_SANDBOX=false

# Quality level passed to agent
QUALITY_LEVEL="production"

PRD Format

{
  "project": "my-feature",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "qualityLevel": "production",
  "feedbackLoops": {
    "typecheck": "pnpm check-types",
    "lint": "pnpm lint",
    "test": "pnpm test"
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "Story title",
      "description": "As a [user], I want [feature]...",
      "acceptanceCriteria": ["Criterion 1", "Criterion 2"],
      "priority": 1,
      "risk": "high",
      "passes": false,
      "notes": ""
    }
  ]
}

Priority: 1 = highest (work first) Risk: high = architecture/unknowns, medium = core logic, low = polish

AGENTS.md

Create AGENTS.md in your project root for persistent conventions:

# Project Agent Instructions

## Code Conventions
- Use TypeScript strict mode
- Follow existing patterns in src/

## Gotchas
- Always update types.ts when adding new API endpoints
- Tests require dev server running

## Key Files
| File | Purpose |
|------|---------|
| src/api/index.ts | API entry point |

Ralph reads this before each iteration and updates it with new learnings.

How It Works

Each iteration:

1. Read context - progress.txt patterns, prd.json, AGENTS.md
2. Select story - Highest-priority where passes: false
3. Implement - Make focused changes for that story
4. Verify - Run feedback loops (typecheck, lint, test)
5. Commit - If checks pass: feat: [ID] - [Title]
6. Update - Mark story complete, append learnings
7. Check - If all done, output <promise>COMPLETE</promise>

Circuit Breaker

Ralph automatically stops if:

• 3+ consecutive errors
• 5+ iterations with no file changes
• Prevents runaway API costs and stuck loops

Docker Sandbox

For true AFK safety, enable Docker sandbox in config:

USE_DOCKER_SANDBOX=true

Requires Docker Desktop 4.50+ with sandbox feature.

Best Practices

Story Sizing

• Small: Each story completable in ~15-30 minutes
• Focused: One logical change per story
• Measurable: Specific acceptance criteria

Prioritization

1. High risk first: Architecture, integrations, unknowns
2. Core logic next: Business rules, data flow
3. Polish last: UI tweaks, cosmetic changes

Feedback Loops

• Typecheck: Catches type errors early
• Lint: Maintains code quality
• Test: Verifies behavior
• Build: Ensures deployability

HITL vs AFK

| Mode | Script | Use Case | |------|--------|----------| | HITL | ralph-once.sh | Learning, debugging, refining prompts | | AFK | ralph-local.sh N | Bulk work, overnight runs |

Start with HITL to build confidence, then go AFK.

Requirements

At least one AI CLI:

• Claude Code - npm install -g @anthropic-ai/claude-code
• Amp - https://ampcode.com
• OpenCode - https://github.com/opencode-ai/opencode

Required tools:

• jq - brew install jq (macOS) or apt install jq (Linux)
• git - For commits and branch management

Optional:

• Docker Desktop 4.50+ - For sandbox mode
• tmux - For monitoring

Importing Requirements

Convert existing specs to Ralph format:

# Markdown PRD
ralph-mode import product-requirements.md

# Text specification
ralph-mode import spec.txt

# Auto-names project from filename
ralph-mode import design-doc.md

# Custom project name
ralph-mode import api-spec.json my-api

The AI will break down requirements into properly-sized user stories.

Monitoring

# Check current status
ralph-mode status

# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# View learnings
cat progress.txt

# Check recent commits
git log --oneline -10

Troubleshooting

Circuit Breaker Tripped

• Check progress.txt for recent errors
• Review last few git commits
• Adjust story size or acceptance criteria

No Progress Detected

• Stories may be too large
• Feedback loops may be failing silently
• Check if correct branch exists

Wrong CLI Used

• Set RALPH_CLI in .ralph/config.sh
• Or ensure preferred CLI is first in PATH

Credits

Inspired by:

• ghuntley/ralph - Original Ralph concept
• snarktank/ralph - Amp implementation
• ralph-orchestrator - Python orchestrator
• ralph-claude-code - Circuit breaker patterns
• Matt Pocock's tips - Best practices

License

MIT