Ralph starter
Bootstrap projects from Figma, Linear, Notion & GitHub specs. The only AI ralph with source integrations.
The most complete Ralph Wiggum implementation.Connect your tools. Run AI coding loops. Ship faster. The project is written primarily in TypeScript, distributed under the MIT License license, first published in 2026. Key topics include: ai, ai-agents, ai-coding-agent, ai-developer-tools, autonomous-coding.
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.
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 to get started.
Table of Contents
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, 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
bashnpm install -g ralph-starter # or npx ralph-starter
After installing, run the setup wizard and verify your environment:
bashralph-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:
bashralph-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?
bashralph-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.):
bashcd 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):
bashcd 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:
bashralph-starter ideas
MCP Server
Use ralph-starter from Claude Desktop or any MCP client:
bashralph-starter mcp
Add to Claude Desktop config:
json{ "mcpServers": { "ralph-starter": { "command": "ralph-starter", "args": ["mcp"] } } }
Available MCP Tools:
ralph_init- Initialize Ralph Playbookralph_plan- Create implementation planralph_run- Execute coding loopralph_status- Check progressralph_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
bashralph-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
bashralph-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_COMPLETEfile in project root.ralph-donemarker file- All tasks marked
[x]inIMPLEMENTATION_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.mdfor 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:
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 commandsPROMPT_plan.md- Planning prompt templatePROMPT_build.md- Building prompt templateIMPLEMENTATION_PLAN.md- Prioritized task listspecs/- 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
bashmkdir 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:
bashralph-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:
markdown[](https://github.com/multivmlabs/ralph-starter)
More styles available at ralphstarter.ai/badge.
License
MIT
Contributors
Showing top 3 contributors by commit count.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
Related Repositories
openclaw/openclaw
Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞
NousResearch/hermes-agent
The agent that grows with you
n8n-io/n8n
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
Significant-Gravitas/AutoGPT
AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
AUTOMATIC1111/stable-diffusion-webui
Stable Diffusion web UI
f/prompts.chat
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete privacy.