https://github.com/multivmlabs/ralph-starter
Bootstrap projects from Figma, Linear, Notion & GitHub specs. The only AI ralph with source integrations.
https://github.com/multivmlabs/ralph-starter
ai ai-agents ai-coding-agent ai-developer-tools autonomous-coding claude-code codex-cli coding-agent figma-to-code github github-automation linear linear-integration notion notion-automation notion-integration opencode ralph-loop ralph-wiggum ralph-wiggum-loop
Last synced: 9 days ago
JSON representation
Bootstrap projects from Figma, Linear, Notion & GitHub specs. The only AI ralph with source integrations.
- Host: GitHub
- URL: https://github.com/multivmlabs/ralph-starter
- Owner: multivmlabs
- License: mit
- Created: 2026-01-21T22:10:21.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-12T17:46:04.000Z (9 days ago)
- Last Synced: 2026-03-12T21:44:58.764Z (9 days ago)
- Topics: ai, ai-agents, ai-coding-agent, ai-developer-tools, autonomous-coding, claude-code, codex-cli, coding-agent, figma-to-code, github, github-automation, linear, linear-integration, notion, notion-automation, notion-integration, opencode, ralph-loop, ralph-wiggum, ralph-wiggum-loop
- Language: TypeScript
- Homepage: https://ralphstarter.ai
- Size: 27.7 MB
- Stars: 86
- Watchers: 0
- Forks: 6
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
The most complete Ralph Wiggum implementation.
Connect your tools. Run AI coding loops. Ship faster.
The easiest way to run Ralph Wiggum autonomous coding loops — pull specs from GitHub, Linear, Notion, Figma, and more, then let AI build it.
Integrations •
Quick Start •
Features •
Docs
---
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 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