Ralphie

Autonomous AI coding loops.

Based on the Ralph Wiggum technique: describe what you want → AI builds it task by task → each task gets committed → come back to working code.

ralphie spec "Todo app with auth"    # Creates spec
ralphie run --all                    # Builds until done

Quick Start

1. Install Ralphie

npm install -g ralphie

2. Set up your AI provider

# Claude (default)
curl -fsSL https://anthropic.com/install-claude.sh | sh

# Or Codex
npm install -g @openai/codex && export OPENAI_API_KEY=sk-...

# Or OpenCode
npm install -g opencode-ai && opencode auth login

3. Build something

# Create a spec
ralphie spec "REST API with JWT auth"

# Run the loop
ralphie run --all
git log --oneline                        # See what was built

What happens next? Ralphie generates a structured spec with research and analysis, then executes task-by-task with fresh context each iteration. Progress lives in git commits—the AI can fail, the loop restarts clean.

How It Works

Each iteration:

1. Fresh context (no accumulated confusion)
2. Reads spec → picks next pending task
3. Implements, tests, commits
4. Exits → loop restarts clean

The insight: Progress lives in git, not the LLM's context. The AI can fail—next iteration starts fresh and sees only committed work.

What makes Ralphie different: Structured specs with task IDs, status tracking, size budgeting, and verify commands. The AI knows exactly what to build, how to check it worked, and when it's done. No ambiguity, no drift.

Key Features

Compound Engineering - Each failure makes the system better:

• Research phase: Fetches framework-specific best practices from skills.sh (React, Next.js, Expo, etc.) and web research
• Dynamic tool selection: Discovers best-in-class libraries for your stack (not hardcoded recommendations)
• Multi-agent review: Security, performance, architecture checks before implementation
• Learnings system: Captures failure→fix transitions as reusable knowledge
• Quality enforcement: >80% test coverage mandatory, typed interfaces required, security by default
• Debug logs: Full audit trail in .ralphie/logs/ viewable with ralphie logs

Senior Engineer Output - Code quality built-in:

• Research recommends current best tools (Zod, bcrypt, expo-auth-session)
• Specs include explicit quality requirements (tests, security, architecture)
• Test validator blocks task completion without >80% coverage
• Clean, maintainable code with proper separation of concerns
• See Code Quality Standards for details

Inspired by EveryInc/compound-engineering-plugin. See Architecture docs for details.

Commands

| Command | Description | |---------|-------------| | ralphie spec "desc" | Generate spec autonomously with research + analysis | | ralphie spec --skip-research | Skip deep research phase | | ralphie spec --skip-analyze | Skip SpecFlow analysis phase | | ralphie run | Run one iteration | | ralphie run -n 5 | Run 5 iterations | | ralphie run --all | Run until spec complete | | ralphie run --review | Run multi-agent review before iteration | | ralphie run --force | Override P1 blocking (use with --review) | | ralphie run --greedy | Multiple tasks per iteration | | ralphie run --headless | JSON output for CI/CD | | ralphie init | Add to existing project | | ralphie validate | Check spec format | | ralphie status | Show progress of active spec | | ralphie spec-list | List active and completed specs | | ralphie logs | View iteration logs (with --tail, --filter) | | ralphie archive | Move completed spec to archive |

Spec Format

Ralphie works from structured specs in .ralphie/specs/active/:

# My Project

Goal: Build a REST API with authentication

## Tasks

### T001: Set up Express with TypeScript
- Status: pending
- Size: M

**Deliverables:**
- Initialize npm project with TypeScript
- Configure Express server
- Add basic health check endpoint

**Verify:** `npm run build && npm test`

---

### T002: Create User model
- Status: pending
- Size: S

**Deliverables:**
- Define User interface
- Add bcrypt password hashing

**Verify:** `npm test`

Tasks transition from pending → in_progress → passed/failed. See Spec Guide for best practices.

Project Structure

After ralphie init, you'll have:

• .ralphie/specs/active/ - Generated specs with task tracking
• .ralphie/logs/ - Timestamped logs (research, spec generation, iterations)
• .ralphie/learnings/ - Captured failure→fix knowledge
• .ralphie/state.txt - Iteration progress log

See Architecture docs for complete structure and file formats.

Troubleshooting

| Problem | Solution | |---------|----------| | command not found: ralphie | npm install -g ralphie | | command not found: claude | export PATH="$HOME/.local/bin:$PATH" | | Missing ANTHROPIC_API_KEY | export ANTHROPIC_API_KEY=sk-ant-... (add to .zshrc) | | Missing OPENAI_API_KEY | export OPENAI_API_KEY=sk-... (add to .zshrc) | | Stuck on same task | Check task status. Run ralphie validate | | No spec found | ralphie spec "description" to create one |

Documentation

• CLI Reference - All commands, flags, harness options
• Spec Guide - Writing effective specs
• Architecture - How the loop works, compound engineering details
• Code Quality Standards - Senior engineer code quality expectations
• Comparison - How Ralphie compares to other tools

Requirements

• Node.js 18+
• Claude Code CLI, OpenAI Codex CLI, or OpenCode CLI
• Git

License

MIT