---
Most AI coding tools work in isolation. You describe a task, AI builds it, done.
**ralph-starter** brings the [Ralph Wiggum technique](https://ghuntley.com/ralph/) 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.
```bash
# 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:
| Integration | Auth Method | What It Fetches |
|-------------|-------------|-----------------|
| **GitHub** | `gh` CLI (recommended) or API token | Issues, PRs, files |
| **Linear** | `linear` CLI or API key | Issues by team/project |
| **Notion** | None (public) or API token (private) | Pages, databases |
| **Figma** | API token | Design specs, tokens, assets & content extraction |
| **URLs** | None | Any public markdown/HTML |
| **Files** | None | Local markdown, PDF |
```bash
# 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](CONTRIBUTING.md) to get started.
---
## Table of Contents
- [Integrations](#integrations)
- [Quick Start](#quick-start)
- [Features](#features)
- [Commands](#commands)
- [Configuration](#api-key-configuration)
- [Contributing](#contributing)
---
### Key Features
| Feature | Description |
|---------|-------------|
| **Integrations** | Pull specs from GitHub, Linear, Notion, Figma, URLs, files |
| **Multi-Agent Support** | Works with Claude Code, Cursor, Copilot, Gemini CLI, and more |
| **Interactive Wizard** | Guided project creation with AI-refined specifications |
| **16+ Workflow Presets** | Pre-configured modes: feature, tdd, debug, review, and more |
| **Circuit Breaker** | Auto-stops stuck loops after repeated failures |
| **Cost Tracking** | Estimates token usage and cost per iteration |
| **Git Automation** | Auto-commit, push, and PR creation |
| **Backpressure Validation** | Run tests/lint/build after each iteration |
| **MCP Server** | Use from Claude Desktop or any MCP client |
### Quick Example
```bash
# 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](https://ghuntley.com/ralph/), 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
```bash
npm install -g ralph-starter
# or
npx ralph-starter
```
After installing, run the setup wizard and verify your environment:
```bash
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:
```bash
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?
```bash
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
```bash
# 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.):
```bash
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):
```bash
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:
```bash
ralph-starter ideas
```
### MCP Server
Use ralph-starter from Claude Desktop or any MCP client:
```bash
ralph-starter mcp
```
Add to Claude Desktop config:
```json
{
"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 providers for internal features:
| Provider | Environment Variable | Description |
|----------|---------------------|-------------|
| **Anthropic** | `ANTHROPIC_API_KEY` | Claude models (default) |
| **OpenAI** | `OPENAI_API_KEY` | GPT-4 and GPT-4o |
| **OpenRouter** | `OPENROUTER_API_KEY` | 100+ models with one API |
These keys are for ralph-starter's internal LLM calls. Coding agents handle their own authentication.
### Git Automation
```bash
ralph-starter run "your task" --commit # Auto-commit after tasks
ralph-starter run "your task" --push # Push to remote
ralph-starter run "your task" --pr # Create PR when done
```
### Backpressure Validation
```bash
ralph-starter run "your task" --validate # Run tests/lint/build after each iteration
```
The `--validate` flag runs test, lint, and build commands (from AGENTS.md or package.json) after each iteration. If validation fails, the agent gets feedback to fix the issues.
### Workflow Presets
Pre-configured settings for common development scenarios:
```bash
# List all 16+ presets
ralph-starter presets
# Use a preset
ralph-starter run --preset feature "build login"
ralph-starter run --preset tdd-red-green "add tests"
ralph-starter run --preset debug "fix the bug"
ralph-starter run --preset refactor "clean up auth module"
ralph-starter run --preset pr-review "review changes"
```
**Available Presets:**
| Category | Presets |
|----------|---------|
| Development | `feature`, `feature-minimal`, `tdd-red-green`, `spec-driven`, `refactor` |
| Debugging | `debug`, `incident-response`, `code-archaeology` |
| Review | `review`, `pr-review`, `adversarial-review` |
| Documentation | `docs`, `documentation-first` |
| Specialized | `api-design`, `migration-safety`, `performance-optimization`, `scientific-method`, `research`, `gap-analysis` |
### Circuit Breaker
Automatically stops loops that are stuck:
```bash
# Stop after 3 consecutive failures (default)
ralph-starter run "build X" --validate
# Custom thresholds
ralph-starter run "build X" --circuit-breaker-failures 2 --circuit-breaker-errors 3
```
The circuit breaker monitors:
- **Consecutive failures**: Stops after N validation failures in a row
- **Same error count**: Stops if the same error repeats N times
### Progress Tracking
Writes iteration logs to `activity.md`:
```bash
# Enabled by default
ralph-starter run "build X"
# Disable if not needed
ralph-starter run "build X" --no-track-progress
```
Each iteration records:
- Timestamp and duration
- Status (completed, failed, blocked)
- Validation results
- Commit info
### File-Based Completion
The loop automatically checks for completion signals:
- `RALPH_COMPLETE` file in project root
- `.ralph-done` marker file
- All tasks marked `[x]` in `IMPLEMENTATION_PLAN.md`
### Rate Limiting
Control API call frequency to manage costs:
```bash
# Limit to 50 calls per hour
ralph-starter run --rate-limit 50 "build X"
```
**When rate limits are reached**, ralph-starter displays detailed stats:
```
⚠ Claude rate limit reached
Rate Limit Stats:
• Session usage: 100% (50K / 50K tokens)
• Requests made: 127 this hour
• Time until reset: ~47 minutes (resets at 04:30 UTC)
Session Progress:
• Tasks completed: 3/5
• Current task: "Add swarm mode CLI flags"
• Branch: auto/github-54
• Iterations completed: 12
To resume when limit resets:
ralph-starter run
Tip: Check your limits at https://claude.ai/settings
```
This helps you:
- Know exactly when you can resume
- Track progress on your current session
- Understand your usage patterns
### Cost Tracking
Track estimated token usage and costs during loops:
```bash
# Cost tracking is enabled by default
ralph-starter run "build X"
# Disable cost tracking
ralph-starter run "build X" --no-track-cost
```
Cost tracking provides:
- **Per-iteration cost** displayed during the loop
- **Running total** of tokens and cost
- **Cost summary** at the end of the loop
- **Cost logged** in `activity.md` for each iteration
- **Projected cost** for remaining iterations (after 3+ iterations)
Supported models for cost estimation:
- Claude 3 Opus ($15/$75 per 1M tokens)
- Claude 3.5 Sonnet ($3/$15 per 1M tokens)
- Claude 3.5 Haiku ($0.25/$1.25 per 1M tokens)
- GPT-4 ($30/$60 per 1M tokens)
- GPT-4 Turbo ($10/$30 per 1M tokens)
## Ralph Playbook Workflow
ralph-starter follows the [Ralph Playbook](https://claytonfarr.github.io/ralph-playbook/) methodology:
```bash
# 1. Initialize Ralph Playbook files
ralph-starter init
# 2. Write specs in specs/ folder
# 3. Create implementation plan
ralph-starter plan
# 4. Execute the plan
ralph-starter run --commit --validate
```
This creates:
- `AGENTS.md` - Agent instructions and validation commands
- `PROMPT_plan.md` - Planning prompt template
- `PROMPT_build.md` - Building prompt template
- `IMPLEMENTATION_PLAN.md` - Prioritized task list
- `specs/` - Specification files
## Commands
| Command | Description |
|---------|-------------|
| `ralph-starter` | Launch interactive wizard |
| `ralph-starter run [task]` | Run an autonomous coding loop |
| `ralph-starter fix [task]` | Fix build errors, lint issues, or design problems |
| `ralph-starter github` | Interactive GitHub issues wizard |
| `ralph-starter linear` | Interactive Linear issues wizard |
| `ralph-starter notion` | Interactive Notion pages wizard |
| `ralph-starter auto` | Batch-process issues from GitHub/Linear |
| `ralph-starter task ` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |
| `ralph-starter integrations ` | Manage integrations (list, help, test, fetch) |
| `ralph-starter plan` | Create implementation plan from specs |
| `ralph-starter init` | Initialize Ralph Playbook in a project |
| `ralph-starter setup` | Configure environment and API keys interactively |
| `ralph-starter check` | Verify system requirements and connectivity |
| `ralph-starter ideas` | Brainstorm project ideas |
| `ralph-starter presets` | List available workflow presets |
| `ralph-starter mcp` | Start as MCP server |
| `ralph-starter config ` | Manage credentials |
| `ralph-starter source ` | Manage input sources (legacy) |
| `ralph-starter skill add ` | Install agent skills |
## Options for `run`
### Core Options
| Flag | Description |
|------|-------------|
| `--auto` | Skip permission prompts **(default: true)** |
| `--no-auto` | Require manual permission approval |
| `--commit` | Auto-commit after tasks |
| `--push` | Push commits to remote |
| `--pr` | Create pull request |
| `--validate` | Run tests/lint/build (backpressure) |
| `--agent ` | Specify agent to use |
| `--max-iterations ` | Max loop iterations (default: 50) |
### Debug Mode
Use `RALPH_DEBUG=1` to see detailed output during execution:
```bash
# See detailed agent output, timing, and prompts
RALPH_DEBUG=1 ralph-starter run "build a todo app"
# Debug with GitHub issue
RALPH_DEBUG=1 ralph-starter run --from github --issue 42
```
Debug mode shows:
- Exact commands being run
- Agent output in real-time
- Timing information
- Error details
### Workflow Presets
| Flag | Description |
|------|-------------|
| `--preset ` | Use a workflow preset (feature, tdd-red-green, debug, etc.) |
```bash
# List all available presets
ralph-starter presets
# Use a preset
ralph-starter run --preset feature "build login page"
ralph-starter run --preset tdd-red-green "add user validation"
ralph-starter run --preset debug "fix the auth bug"
```
### Exit Detection
| Flag | Description |
|------|-------------|
| `--completion-promise ` | Custom string to detect task completion |
| `--require-exit-signal` | Require explicit `EXIT_SIGNAL: true` for completion |
```bash
# Stop when agent outputs "FEATURE_DONE"
ralph-starter run --completion-promise "FEATURE_DONE" "build X"
# Require explicit exit signal
ralph-starter run --require-exit-signal "build Y"
```
### Safety Controls
| Flag | Description |
|------|-------------|
| `--rate-limit ` | Max API calls per hour (default: unlimited) |
| `--circuit-breaker-failures ` | Max consecutive failures before stopping (default: 3) |
| `--circuit-breaker-errors ` | Max same error occurrences before stopping (default: 5) |
| `--track-progress` | Write progress to activity.md (default: true) |
| `--no-track-progress` | Disable progress tracking |
| `--track-cost` | Track token usage and estimated cost (default: true) |
| `--no-track-cost` | Disable cost tracking |
```bash
# Limit to 50 API calls per hour
ralph-starter run --rate-limit 50 "build X"
# Stop after 2 consecutive failures
ralph-starter run --circuit-breaker-failures 2 "build Y"
```
### Source Options
| Flag | Description |
|------|-------------|
| `--from ` | Fetch spec from source |
| `--project ` | Project filter for sources |
| `--label ` | Label filter for sources |
| `--status ` | Status filter for sources |
| `--limit ` | Max items from source |
| `--issue ` | Specific issue number (GitHub) |
| `--output-dir ` | Directory to run task in (skips prompt) |
| `--prd ` | Read tasks from markdown |
## Options for `fix`
| Flag | Description |
|------|-------------|
| `--scan` | Force full project scan (build + lint + typecheck + tests) |
| `--agent ` | Specify agent to use (default: auto-detect) |
| `--commit` | Auto-commit the fix |
| `--max-iterations ` | Max fix iterations (default: 3) |
| `--output-dir ` | Project directory (default: cwd) |
```bash
# Fix build/lint errors automatically
ralph-starter fix
# Fix a specific design/visual issue
ralph-starter fix "fix the paddings and make the colors brighter"
# Full scan with auto-commit
ralph-starter fix --scan --commit
```
For design-related tasks (CSS, colors, spacing, etc.), the fix command automatically:
- Detects and applies installed design skills
- Instructs the agent to visually verify changes via browser screenshots
## Config Commands
```bash
# Set credentials
ralph-starter config set linear.apiKey
ralph-starter config set notion.token
ralph-starter config set github.token
# View config
ralph-starter config list
ralph-starter config get linear.apiKey
# Remove
ralph-starter config delete linear.apiKey
```
## Example: Build a SaaS Dashboard
```bash
mkdir my-saas && cd my-saas
git init
ralph-starter run "Create a SaaS dashboard with:
- User authentication (email/password)
- Stripe subscription billing
- Dashboard with usage metrics
- Dark mode support" --commit --pr --validate
# Watch the magic happen...
# Loop 1: Setting up Next.js project...
# Validation passed
# Committed: chore: initialize Next.js with TypeScript
# Loop 2: Adding authentication...
# ✓ Validation passed
# ✓ Committed: feat(auth): add NextAuth with email provider
# ...
# ✓ Created PR #1: "Build SaaS dashboard"
```
## Testing ralph-starter
### Quick Test (No API Keys)
You can test ralph-starter with public URLs - no API keys required:
```bash
# Test with a public GitHub gist or raw markdown
ralph-starter run --from https://raw.githubusercontent.com/multivmlabs/ralph-starter/main/README.md
# Test with GitHub issues (requires gh CLI login)
gh auth login
ralph-starter run --from github --project multivmlabs/ralph-starter --label "enhancement"
```
### Testing the Wizard
```bash
# Launch the interactive wizard
ralph-starter
# Or test idea mode
ralph-starter ideas
```
### Testing with Your Own Specs
```bash
# Create a simple spec file
echo "Build a simple counter app with React" > my-spec.md
# Run with local file
ralph-starter run --from ./my-spec.md
```
### Verifying Source Connectivity
Before using an integration, verify it's working:
```bash
# Check what integrations are available
ralph-starter integrations list
# Test each integration
ralph-starter integrations test github
ralph-starter integrations test linear
ralph-starter integrations test notion
# Preview items (dry run)
ralph-starter integrations fetch linear "My Project" --limit 3
```
## API Key Configuration
### Option 1: Environment Variables (Recommended for Developers)
Set environment variables in your shell profile or `.env` file:
```bash
# Add to ~/.bashrc, ~/.zshrc, or .env file
export LINEAR_API_KEY=lin_api_xxxxx
export NOTION_API_KEY=secret_xxxxx
export GITHUB_TOKEN=ghp_xxxxx
```
Environment variables take precedence over the config file.
### Option 2: Config Command
Use the CLI to store credentials:
```bash
ralph-starter config set linear.apiKey lin_api_xxxxx
ralph-starter config set notion.token secret_xxxxx
ralph-starter config set github.token ghp_xxxxx
```
Credentials are stored in `~/.ralph-starter/sources.json`.
### Environment Variable Reference
| Source | Environment Variable | Config Key |
|--------|---------------------|------------|
| Linear | `LINEAR_API_KEY` | `linear.apiKey` |
| Notion | `NOTION_API_KEY` | `notion.token` |
| GitHub | `GITHUB_TOKEN` | `github.token` |
| Figma | `FIGMA_TOKEN` | `figma.token` |
## Requirements
- Node.js 18+
- At least one coding agent installed (Claude Code, Cursor, etc.)
- Git (for automation features)
- GitHub CLI `gh` (for PR creation and GitHub source)
## Documentation
Full documentation available at: https://ralphstarter.ai
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- **Feature requests & ideas**: [ralph-ideas](https://github.com/multivmlabs/ralph-ideas)
- **Project templates**: [ralph-templates](https://github.com/multivmlabs/ralph-templates)
For creating custom integrations, agents, or using the programmatic API, see the [Developer Extension Guide](https://ralphstarter.ai/docs/guides/extending-ralph-starter).
## Badge
Using ralph-starter? Add the badge to your README:
[](https://github.com/multivmlabs/ralph-starter)
```markdown
[](https://github.com/multivmlabs/ralph-starter)
```
More styles available at [ralphstarter.ai/badge](https://ralphstarter.ai/badge).
## License
MIT
