KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#codex #developer-tools #typescript #ai-agents #claude-code #dsh #dsh-plugin #python #mcp #react #cli #macos

ralph-starter

★ 105 Open GitHub ↗

Bootstrap projects from Figma, Linear, Notion & GitHub specs. The only AI ralph with source integrations.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h3 align="center">
 The most complete Ralph Wiggum implementation. Connect your tools. Run AI coding loops. Ship faster.
</h3>

The easiest way to run Ralph Wiggum autonomous coding loops — pull specs from GitHub, Linear, Notion, Figma, and more, then let AI build it.

<a href="#integrations">Integrations</a> •
 <a href="#quick-start">Quick Start</a> •
 <a href="#features">Features</a> •
 <a href="https://ralphstarter.ai">Docs</a>

---

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 <action>` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |
| `ralph-starter integrations <action>` | 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 <action>` | Manage credentials |
| `ralph-starter source <action>` | Manage input sources (legacy) |
| `ralph-starter skill add <repo>` | 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 <name>` | Specify agent to use |
| `--max-iterations <n>` | 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 <name>` | 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 <string>` | 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 <n>` | Max API calls per hour (default: unlimited) |
| `--circuit-breaker-failures <n>` | Max consecutive failures before stopping (default: 3) |
| `--circuit-breaker-errors <n>` | 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 <source>` | Fetch spec from source |
| `--project <name>` | Project filter for sources |
| `--label <name>` | Label filter for sources |
| `--status <status>` | Status filter for sources |
| `--limit <n>` | Max items from source |
| `--issue <n>` | Specific issue number (GitHub) |
| `--output-dir <path>` | Directory to run task in (skips prompt) |
| `--prd <file>` | Read tasks from markdown |

## Options for `fix`

| Flag | Description |
|------|-------------|
| `--scan` | Force full project scan (build + lint + typecheck + tests) |
| `--agent <name>` | Specify agent to use (default: auto-detect) |
| `--commit` | Auto-commit the fix |
| `--max-iterations <n>` | Max fix iterations (default: 3) |
| `--output-dir <path>` | 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 <key>
ralph-starter config set notion.token <token>
ralph-starter config set github.token <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:

[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)

```markdown
[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)
```

More styles available at [ralphstarter.ai/badge](https://ralphstarter.ai/badge).

## License

MIT

ralph-starter

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README