ralph-starter

Most AI coding tools work in isolation. You describe a task, AI builds it, done.

ralph-starter brings the Ralph Wiggum technique to production. It connects to your existing workflow — pulling specs from GitHub issues, Linear tickets, Notion docs, or any URL — then runs autonomous Ralph Wiggum loops until the task is complete. One command to go from spec to shipped code.

# Build from a GitHub issue
ralph-starter run --from github --project myorg/myrepo --label "ready"

# Build from a Linear ticket
ralph-starter run --from linear --project "Mobile App" --label "sprint-1"

# Build from a Notion spec
ralph-starter run --from notion --project "https://notion.so/Product-Spec-abc123"

# Or just describe what you want
ralph-starter run "build a todo app with React" --commit

Integrations

ralph-starter integrates with your favorite tools out of the box:

# Check available integrations
ralph-starter integrations list

# Test connectivity
ralph-starter integrations test github
ralph-starter integrations test linear

# Preview data before running
ralph-starter integrations fetch github owner/repo

Want more integrations? PRs welcome! See CONTRIBUTING.md to get started.

Table of Contents

• Integrations
• Quick Start
• Features
• Commands
• Configuration
• Contributing

Key Features

Quick Example

# Simple task
ralph-starter run "build a todo app" --commit --validate

# With preset
ralph-starter run --preset tdd-red-green "add user authentication"

# With safety controls
ralph-starter run --rate-limit 50 --circuit-breaker-failures 3 "build X"

# Interactive wizard
ralph-starter

What is Ralph Wiggum?

The Ralph Wiggum technique is an autonomous AI coding pattern where you run a coding agent (like Claude Code, Codex, or Cursor) in a loop — feeding errors back into the agent until the task is complete. Originally described by Geoffrey Huntley, the Ralph Wiggum loop has become one of the most popular approaches for autonomous AI development.

ralph-starter is the production-grade Ralph Wiggum implementation — it adds integrations, safety controls (circuit breakers, rate limiting, cost tracking), git automation, validation backpressure, and multi-agent support on top of the core Ralph Wiggum loop pattern. Instead of a bare bash script, you get a full orchestration engine.

Why ralph-starter over a raw Ralph Wiggum script?

• Spec-driven: Pull tasks from GitHub, Linear, Notion, Figma — not just manual prompts
• Safe: Circuit breakers stop stuck loops, rate limiters control costs
• Multi-agent: Works with 8+ coding agents, not just one
• Observable: Cost tracking, progress logs, iteration history
• Automated: Auto-commit, push, and PR creation built in

Installation

npm install -g ralph-starter
# or
npx ralph-starter

After installing, run the setup wizard and verify your environment:

ralph-starter setup    # Configure API keys and preferences
ralph-starter check    # Verify system requirements and connectivity

Quick Start

For Everyone (Non-Developers Welcome!)

Just run ralph-starter with no arguments to launch the interactive wizard:

ralph-starter

The wizard will:

1. Ask if you have a project idea (or help you brainstorm one)
2. Refine your idea with AI
3. Let you customize the tech stack
4. Build your project automatically

Don't Know What to Build?

ralph-starter ideas

This launches Idea Mode - a brainstorming session to help you discover project ideas:

• Brainstorm with AI - Get creative suggestions
• See trending ideas - Based on 2025-2026 tech trends
• Based on my skills - Personalized to technologies you know
• Solve a problem - Help fix something that frustrates you

For Developers

# Run a single task
ralph-starter run "build a todo app with React"

# With git automation
ralph-starter run "add user authentication" --commit --pr

# With validation (backpressure)
ralph-starter run "refactor auth" --commit --validate

# Fetch specs from external sources
ralph-starter run --from https://example.com/spec.md
ralph-starter run --from github --project myorg/myrepo --label "ready"
ralph-starter run --from linear --project "Mobile App"

# Fetch a specific GitHub issue
ralph-starter run --from github --project owner/repo --issue 123

# Specify output directory (skips "where to run?" prompt)
ralph-starter run --from github --project owner/repo --issue 42 --output-dir ~/projects/new-app

Working with Existing Projects

ralph-starter automatically detects existing projects when you run the wizard:

Ralph Playbook Project (has AGENTS.md, IMPLEMENTATION_PLAN.md, etc.):

cd my-ralph-project
ralph-starter

The wizard will detect the Ralph Playbook files and let you:

• Continue working (run the build loop)
• Regenerate the implementation plan
• Add new specs

Language Project (has package.json, pyproject.toml, Cargo.toml, go.mod):

cd my-existing-app
ralph-starter

The wizard will detect the project type and let you:

• Add features to the existing project
• Create a new project in a subfolder

Features

Interactive Wizard

Launch with ralph-starter (no args) for a guided experience:

• Describe your idea in plain English
• AI refines and suggests features
• Choose your tech stack
• Auto-runs init → plan → build

Idea Mode

For users who don't know what to build yet:

ralph-starter ideas

MCP Server

Use ralph-starter from Claude Desktop or any MCP client:

ralph-starter mcp

Add to Claude Desktop config:

{
  "mcpServers": {
    "ralph-starter": {
      "command": "ralph-starter",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools:

• ralph_init - Initialize Ralph Playbook
• ralph_plan - Create implementation plan
• ralph_run - Execute coding loop
• ralph_status - Check progress
• ralph_validate - Run tests/lint/build

Multi-Agent Support

Works with your favorite coding agents:

• Claude Code (recommended)
• Cursor
• OpenCode
• OpenAI Codex
• GitHub Copilot
• Gemini CLI
• Amp
• Openclaw

LLM Providers

ralph-starter supports multiple LLM