ralph-starter

Connect your tools. Run AI coding loops. Ship faster.

Pull specs from GitHub, Linear, Notion, Figma, and more — then let AI build it autonomously.

Integrations • Quick Start • Features • Docs

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

ralph-starter is different. It connects to your existing workflow — pulling specs from GitHub issues, Linear tickets, Notion docs, or any URL — then runs autonomous AI loops until the task is complete.

# 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

# 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

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

# 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?

Learn about the Ralph Wiggum technique at ghuntley.com/ralph.

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:

• Ask if you have a project idea (or help you brainstorm one)
• Refine your idea with AI
• Let you customize the tech stack
• 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 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

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

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:

# 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:

# 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:

# 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:

# 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:

# 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 methodology:

# 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 auto	Batch-process issues from GitHub/Linear
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:

# 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.)

# 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

# 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

# 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)

# 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

# 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

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:

# 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

# Launch the interactive wizard
ralph-starter

# Or test idea mode
ralph-starter ideas

Testing with Your Own Specs

# 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:

# 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:

# 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:

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 for guidelines.

• Feature requests & ideas: ralph-ideas
• Project templates: ralph-templates

For creating custom integrations, agents, or using the programmatic API, see the Developer Extension Guide.

Badge

Using ralph-starter? Add the badge to your README:

[![built with ralph-starter](https://ralphstarter.ai/img/[e-mail])](https://github.com/multivmlabs/ralph-starter)

More styles available at ralphstarter.ai/badge.

License

MIT