{"id":47164926,"url":"https://github.com/multivmlabs/ralph-starter","last_synced_at":"2026-03-13T04:01:15.348Z","repository":{"id":336161984,"uuid":"1139379321","full_name":"multivmlabs/ralph-starter","owner":"multivmlabs","description":"Bootstrap projects from Figma, Linear, Notion \u0026 GitHub specs. The only AI ralph with source integrations.","archived":false,"fork":false,"pushed_at":"2026-03-12T17:46:04.000Z","size":29054,"stargazers_count":86,"open_issues_count":16,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-12T21:44:58.764Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://ralphstarter.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/multivmlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"rubenmarcus"}},"created_at":"2026-01-21T22:10:21.000Z","updated_at":"2026-03-12T16:12:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"0586d9c2-03cf-4c7d-bafe-918ef462929f","html_url":"https://github.com/multivmlabs/ralph-starter","commit_stats":null,"previous_names":["rubenmarcus/ralph-starter","multivmlabs/ralph-starter"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/multivmlabs/ralph-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multivmlabs%2Fralph-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multivmlabs%2Fralph-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multivmlabs%2Fralph-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multivmlabs%2Fralph-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multivmlabs","download_url":"https://codeload.github.com/multivmlabs/ralph-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multivmlabs%2Fralph-starter/sbom","scorecard":{"id":1243227,"data":{"date":"2026-02-11T12:27:09Z","repo":{"name":"github.com/multivmlabs/ralph-starter","commit":"3265c7f5d088bde073f5c7fdf2760b97bbce4d2b"},"scorecard":{"version":"v5.3.0","commit":"c22063e786c11f9dd714d777a687ff7c4599b600"},"score":6.4,"checks":[{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":7,"reason":"Found 12/16 approved changesets -- score normalized to 7","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#code-review"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#security-policy"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#dependency-update-tool"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/security.yml:24","Info: jobLevel 'contents' permission set to 'read': .github/workflows/security.yml:64","Info: topLevel 'contents' permission set to 'read': .github/workflows/auto-label.yml:8","Info: topLevel 'contents' permission set to 'read': .github/workflows/bundle-analysis.yml:13","Info: topLevel 'contents' permission set to 'read': .github/workflows/ci.yml:16","Warn: topLevel 'deployments' permission set to 'write': .github/workflows/deploy-docs.yml:15","Info: topLevel 'contents' permission set to 'read': .github/workflows/deploy-docs.yml:14","Info: topLevel 'contents' permission set to 'read': .github/workflows/docs-check.yml:12","Warn: topLevel 'contents' permission set to 'write': .github/workflows/docs-seo-aeo.yml:22","Info: topLevel 'contents' permission set to 'read': .github/workflows/pr-issue-check.yml:8","Info: topLevel 'contents' permission set to 'read': .github/workflows/pr-title.yml:8","Info: topLevel 'pull-requests' permission set to 'read': .github/workflows/pr-title.yml:9","Warn: topLevel 'contents' permission set to 'write': .github/workflows/prepare-release.yml:10","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release-on-tag.yml:9","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:10","Info: topLevel 'contents' permission set to 'read': .github/workflows/security.yml:15","Info: topLevel 'actions' permission set to 'read': .github/workflows/security.yml:16","Warn: topLevel 'contents' permission set to 'write': .github/workflows/stable-release.yml:16","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":8,"reason":"dependency not pinned by hash detected -- score normalized to 8","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:53: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy-docs.yml:73: update your workflow using https://app.stepsecurity.io/secureworkflow/multivmlabs/ralph-starter/deploy-docs.yml/main?enable=pin","Info:  35 out of  38 GitHub-owned GitHubAction dependencies pinned","Info:  16 out of  19 third-party GitHubAction dependencies pinned","Info:   1 out of   1 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#cii-best-practices"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#signed-releases"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#fuzzing"}},{"name":"SAST","score":9,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 28 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#sast"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/release.yml:127"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#packaging"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#license"}},{"name":"Branch-Protection","score":3,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Info: 'branch protection settings apply to administrators' is required to merge on branch 'main'","Warn: 'stale review dismissal' is disabled on branch 'main'","Warn: branch 'main' does not require approvers","Warn: codeowners review is not required on branch 'main'","Warn: 'last push approval' is disabled on branch 'main'","Warn: no status checks found to merge onto branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":8,"reason":"2 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-xxjr-mmjv-4gpg","Warn: Project is vulnerable to: GHSA-52f5-9888-hmc6"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#vulnerabilities"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: found contributions from: multivmlabs"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#contributors"}},{"name":"CI-Tests","score":9,"reason":"29 out of 30 merged PRs checked by a CI test -- score normalized to 9","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/c22063e786c11f9dd714d777a687ff7c4599b600/docs/checks.md#ci-tests"}}]},"last_synced_at":"2026-02-12T00:55:06.847Z","repository_id":336161984,"created_at":"2026-02-12T00:55:06.848Z","updated_at":"2026-02-12T00:55:06.848Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30457983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T03:55:51.346Z","status":"ssl_error","status_checked_at":"2026-03-13T03:55:33.055Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-03-13T04:00:43.665Z","updated_at":"2026-03-13T04:01:15.339Z","avatar_url":"https://github.com/multivmlabs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/rubenmarcus"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"ralph.png\" alt=\"Ralph Wiggum\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ralphstarter.ai/badge\"\u003e\u003cimg src=\"https://ralphstarter.ai/img/badge-built-with@2x.png\" alt=\"built with ralph-starter\" height=\"28\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/ralph-starter\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/ralph-starter.svg?style=flat-square\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/ralph-starter\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/ralph-starter.svg?style=flat-square\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/multivmlabs/ralph-starter/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/ralph-starter.svg?style=flat-square\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/multivmlabs/ralph-starter/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/multivmlabs/ralph-starter/ci.yml?branch=main\u0026style=flat-square\" alt=\"build status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/multivmlabs/ralph-starter/actions/workflows/security.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/multivmlabs/ralph-starter/security.yml?branch=main\u0026style=flat-square\u0026label=security\" alt=\"security scanning\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://securityscorecards.dev/viewer/?uri=github.com/multivmlabs/ralph-starter\"\u003e\u003cimg src=\"https://img.shields.io/ossf-scorecard/github.com/multivmlabs/ralph-starter?style=flat-square\u0026label=scorecard\" alt=\"OSSF Scorecard\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/multivmlabs/ralph-starter\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/multivmlabs/ralph-starter?style=flat-square\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e\n  \u003cstrong\u003eThe most complete Ralph Wiggum implementation.\u003cbr/\u003eConnect your tools. Run AI coding loops. Ship faster.\u003c/strong\u003e\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eThe easiest way to run Ralph Wiggum autonomous coding loops — pull specs from GitHub, Linear, Notion, Figma, and more, then let AI build it.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#integrations\"\u003eIntegrations\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"https://ralphstarter.ai\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\nMost AI coding tools work in isolation. You describe a task, AI builds it, done.\n\n**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.\n\n```bash\n# Build from a GitHub issue\nralph-starter run --from github --project myorg/myrepo --label \"ready\"\n\n# Build from a Linear ticket\nralph-starter run --from linear --project \"Mobile App\" --label \"sprint-1\"\n\n# Build from a Notion spec\nralph-starter run --from notion --project \"https://notion.so/Product-Spec-abc123\"\n\n# Or just describe what you want\nralph-starter run \"build a todo app with React\" --commit\n```\n\n---\n\n## Integrations\n\nralph-starter integrates with your favorite tools out of the box:\n\n| Integration | Auth Method | What It Fetches |\n|-------------|-------------|-----------------|\n| **GitHub** | `gh` CLI (recommended) or API token | Issues, PRs, files |\n| **Linear** | `linear` CLI or API key | Issues by team/project |\n| **Notion** | None (public) or API token (private) | Pages, databases |\n| **Figma** | API token | Design specs, tokens, assets \u0026 content extraction |\n| **URLs** | None | Any public markdown/HTML |\n| **Files** | None | Local markdown, PDF |\n\n```bash\n# Check available integrations\nralph-starter integrations list\n\n# Test connectivity\nralph-starter integrations test github\nralph-starter integrations test linear\n\n# Preview data before running\nralph-starter integrations fetch github owner/repo\n```\n\n\u003e **Want more integrations?** PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\n---\n\n## Table of Contents\n\n- [Integrations](#integrations)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Commands](#commands)\n- [Configuration](#api-key-configuration)\n- [Contributing](#contributing)\n\n---\n\n### Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Integrations** | Pull specs from GitHub, Linear, Notion, Figma, URLs, files |\n| **Multi-Agent Support** | Works with Claude Code, Cursor, Copilot, Gemini CLI, and more |\n| **Interactive Wizard** | Guided project creation with AI-refined specifications |\n| **16+ Workflow Presets** | Pre-configured modes: feature, tdd, debug, review, and more |\n| **Circuit Breaker** | Auto-stops stuck loops after repeated failures |\n| **Cost Tracking** | Estimates token usage and cost per iteration |\n| **Git Automation** | Auto-commit, push, and PR creation |\n| **Backpressure Validation** | Run tests/lint/build after each iteration |\n| **MCP Server** | Use from Claude Desktop or any MCP client |\n\n### Quick Example\n\n```bash\n# Simple task\nralph-starter run \"build a todo app\" --commit --validate\n\n# With preset\nralph-starter run --preset tdd-red-green \"add user authentication\"\n\n# With safety controls\nralph-starter run --rate-limit 50 --circuit-breaker-failures 3 \"build X\"\n\n# Interactive wizard\nralph-starter\n```\n\n---\n\n## What is Ralph Wiggum?\n\nThe **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.\n\n**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.\n\n**Why ralph-starter over a raw Ralph Wiggum script?**\n- **Spec-driven**: Pull tasks from GitHub, Linear, Notion, Figma — not just manual prompts\n- **Safe**: Circuit breakers stop stuck loops, rate limiters control costs\n- **Multi-agent**: Works with 8+ coding agents, not just one\n- **Observable**: Cost tracking, progress logs, iteration history\n- **Automated**: Auto-commit, push, and PR creation built in\n\n## Installation\n\n```bash\nnpm install -g ralph-starter\n# or\nnpx ralph-starter\n```\n\nAfter installing, run the setup wizard and verify your environment:\n\n```bash\nralph-starter setup    # Configure API keys and preferences\nralph-starter check    # Verify system requirements and connectivity\n```\n\n## Quick Start\n\n### For Everyone (Non-Developers Welcome!)\n\nJust run `ralph-starter` with no arguments to launch the interactive wizard:\n\n```bash\nralph-starter\n```\n\nThe wizard will:\n1. Ask if you have a project idea (or help you brainstorm one)\n2. Refine your idea with AI\n3. Let you customize the tech stack\n4. Build your project automatically\n\n### Don't Know What to Build?\n\n```bash\nralph-starter ideas\n```\n\nThis launches **Idea Mode** - a brainstorming session to help you discover project ideas:\n- **Brainstorm with AI** - Get creative suggestions\n- **See trending ideas** - Based on 2025-2026 tech trends\n- **Based on my skills** - Personalized to technologies you know\n- **Solve a problem** - Help fix something that frustrates you\n\n### For Developers\n\n```bash\n# Run a single task\nralph-starter run \"build a todo app with React\"\n\n# With git automation\nralph-starter run \"add user authentication\" --commit --pr\n\n# With validation (backpressure)\nralph-starter run \"refactor auth\" --commit --validate\n\n# Fetch specs from external sources\nralph-starter run --from https://example.com/spec.md\nralph-starter run --from github --project myorg/myrepo --label \"ready\"\nralph-starter run --from linear --project \"Mobile App\"\n\n# Fetch a specific GitHub issue\nralph-starter run --from github --project owner/repo --issue 123\n\n# Specify output directory (skips \"where to run?\" prompt)\nralph-starter run --from github --project owner/repo --issue 42 --output-dir ~/projects/new-app\n```\n\n### Working with Existing Projects\n\nralph-starter automatically detects existing projects when you run the wizard:\n\n**Ralph Playbook Project** (has AGENTS.md, IMPLEMENTATION_PLAN.md, etc.):\n```bash\ncd my-ralph-project\nralph-starter\n```\nThe wizard will detect the Ralph Playbook files and let you:\n- Continue working (run the build loop)\n- Regenerate the implementation plan\n- Add new specs\n\n**Language Project** (has package.json, pyproject.toml, Cargo.toml, go.mod):\n```bash\ncd my-existing-app\nralph-starter\n```\nThe wizard will detect the project type and let you:\n- Add features to the existing project\n- Create a new project in a subfolder\n\n## Features\n\n### Interactive Wizard\nLaunch with `ralph-starter` (no args) for a guided experience:\n- Describe your idea in plain English\n- AI refines and suggests features\n- Choose your tech stack\n- Auto-runs init → plan → build\n\n### Idea Mode\nFor users who don't know what to build yet:\n```bash\nralph-starter ideas\n```\n\n### MCP Server\nUse ralph-starter from Claude Desktop or any MCP client:\n\n```bash\nralph-starter mcp\n```\n\nAdd to Claude Desktop config:\n```json\n{\n  \"mcpServers\": {\n    \"ralph-starter\": {\n      \"command\": \"ralph-starter\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n**Available MCP Tools:**\n- `ralph_init` - Initialize Ralph Playbook\n- `ralph_plan` - Create implementation plan\n- `ralph_run` - Execute coding loop\n- `ralph_status` - Check progress\n- `ralph_validate` - Run tests/lint/build\n\n### Multi-Agent Support\nWorks with your favorite coding agents:\n- **Claude Code** (recommended)\n- **Cursor**\n- **OpenCode**\n- **OpenAI Codex**\n- **GitHub Copilot**\n- **Gemini CLI**\n- **Amp**\n- **Openclaw**\n\n### LLM Providers\nralph-starter supports multiple LLM providers for internal features:\n\n| Provider | Environment Variable | Description |\n|----------|---------------------|-------------|\n| **Anthropic** | `ANTHROPIC_API_KEY` | Claude models (default) |\n| **OpenAI** | `OPENAI_API_KEY` | GPT-4 and GPT-4o |\n| **OpenRouter** | `OPENROUTER_API_KEY` | 100+ models with one API |\n\nThese keys are for ralph-starter's internal LLM calls. Coding agents handle their own authentication.\n\n### Git Automation\n```bash\nralph-starter run \"your task\" --commit      # Auto-commit after tasks\nralph-starter run \"your task\" --push        # Push to remote\nralph-starter run \"your task\" --pr          # Create PR when done\n```\n\n### Backpressure Validation\n```bash\nralph-starter run \"your task\" --validate    # Run tests/lint/build after each iteration\n```\n\nThe `--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.\n\n### Workflow Presets\n\nPre-configured settings for common development scenarios:\n\n```bash\n# List all 16+ presets\nralph-starter presets\n\n# Use a preset\nralph-starter run --preset feature \"build login\"\nralph-starter run --preset tdd-red-green \"add tests\"\nralph-starter run --preset debug \"fix the bug\"\nralph-starter run --preset refactor \"clean up auth module\"\nralph-starter run --preset pr-review \"review changes\"\n```\n\n**Available Presets:**\n| Category | Presets |\n|----------|---------|\n| Development | `feature`, `feature-minimal`, `tdd-red-green`, `spec-driven`, `refactor` |\n| Debugging | `debug`, `incident-response`, `code-archaeology` |\n| Review | `review`, `pr-review`, `adversarial-review` |\n| Documentation | `docs`, `documentation-first` |\n| Specialized | `api-design`, `migration-safety`, `performance-optimization`, `scientific-method`, `research`, `gap-analysis` |\n\n### Circuit Breaker\n\nAutomatically stops loops that are stuck:\n\n```bash\n# Stop after 3 consecutive failures (default)\nralph-starter run \"build X\" --validate\n\n# Custom thresholds\nralph-starter run \"build X\" --circuit-breaker-failures 2 --circuit-breaker-errors 3\n```\n\nThe circuit breaker monitors:\n- **Consecutive failures**: Stops after N validation failures in a row\n- **Same error count**: Stops if the same error repeats N times\n\n### Progress Tracking\n\nWrites iteration logs to `activity.md`:\n\n```bash\n# Enabled by default\nralph-starter run \"build X\"\n\n# Disable if not needed\nralph-starter run \"build X\" --no-track-progress\n```\n\nEach iteration records:\n- Timestamp and duration\n- Status (completed, failed, blocked)\n- Validation results\n- Commit info\n\n### File-Based Completion\n\nThe loop automatically checks for completion signals:\n- `RALPH_COMPLETE` file in project root\n- `.ralph-done` marker file\n- All tasks marked `[x]` in `IMPLEMENTATION_PLAN.md`\n\n### Rate Limiting\n\nControl API call frequency to manage costs:\n\n```bash\n# Limit to 50 calls per hour\nralph-starter run --rate-limit 50 \"build X\"\n```\n\n**When rate limits are reached**, ralph-starter displays detailed stats:\n\n```\n⚠ Claude rate limit reached\n\nRate Limit Stats:\n  • Session usage: 100% (50K / 50K tokens)\n  • Requests made: 127 this hour\n  • Time until reset: ~47 minutes (resets at 04:30 UTC)\n\nSession Progress:\n  • Tasks completed: 3/5\n  • Current task: \"Add swarm mode CLI flags\"\n  • Branch: auto/github-54\n  • Iterations completed: 12\n\nTo resume when limit resets:\n  ralph-starter run\n\nTip: Check your limits at https://claude.ai/settings\n```\n\nThis helps you:\n- Know exactly when you can resume\n- Track progress on your current session\n- Understand your usage patterns\n\n### Cost Tracking\n\nTrack estimated token usage and costs during loops:\n\n```bash\n# Cost tracking is enabled by default\nralph-starter run \"build X\"\n\n# Disable cost tracking\nralph-starter run \"build X\" --no-track-cost\n```\n\nCost tracking provides:\n- **Per-iteration cost** displayed during the loop\n- **Running total** of tokens and cost\n- **Cost summary** at the end of the loop\n- **Cost logged** in `activity.md` for each iteration\n- **Projected cost** for remaining iterations (after 3+ iterations)\n\nSupported models for cost estimation:\n- Claude 3 Opus ($15/$75 per 1M tokens)\n- Claude 3.5 Sonnet ($3/$15 per 1M tokens)\n- Claude 3.5 Haiku ($0.25/$1.25 per 1M tokens)\n- GPT-4 ($30/$60 per 1M tokens)\n- GPT-4 Turbo ($10/$30 per 1M tokens)\n\n## Ralph Playbook Workflow\n\nralph-starter follows the [Ralph Playbook](https://claytonfarr.github.io/ralph-playbook/) methodology:\n\n```bash\n# 1. Initialize Ralph Playbook files\nralph-starter init\n\n# 2. Write specs in specs/ folder\n\n# 3. Create implementation plan\nralph-starter plan\n\n# 4. Execute the plan\nralph-starter run --commit --validate\n```\n\nThis creates:\n- `AGENTS.md` - Agent instructions and validation commands\n- `PROMPT_plan.md` - Planning prompt template\n- `PROMPT_build.md` - Building prompt template\n- `IMPLEMENTATION_PLAN.md` - Prioritized task list\n- `specs/` - Specification files\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `ralph-starter` | Launch interactive wizard |\n| `ralph-starter run [task]` | Run an autonomous coding loop |\n| `ralph-starter fix [task]` | Fix build errors, lint issues, or design problems |\n| `ralph-starter auto` | Batch-process issues from GitHub/Linear |\n| `ralph-starter task \u003caction\u003e` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |\n| `ralph-starter integrations \u003caction\u003e` | Manage integrations (list, help, test, fetch) |\n| `ralph-starter plan` | Create implementation plan from specs |\n| `ralph-starter init` | Initialize Ralph Playbook in a project |\n| `ralph-starter setup` | Configure environment and API keys interactively |\n| `ralph-starter check` | Verify system requirements and connectivity |\n| `ralph-starter ideas` | Brainstorm project ideas |\n| `ralph-starter presets` | List available workflow presets |\n| `ralph-starter mcp` | Start as MCP server |\n| `ralph-starter config \u003caction\u003e` | Manage credentials |\n| `ralph-starter source \u003caction\u003e` | Manage input sources (legacy) |\n| `ralph-starter skill add \u003crepo\u003e` | Install agent skills |\n\n## Options for `run`\n\n### Core Options\n\n| Flag | Description |\n|------|-------------|\n| `--auto` | Skip permission prompts **(default: true)** |\n| `--no-auto` | Require manual permission approval |\n| `--commit` | Auto-commit after tasks |\n| `--push` | Push commits to remote |\n| `--pr` | Create pull request |\n| `--validate` | Run tests/lint/build (backpressure) |\n| `--agent \u003cname\u003e` | Specify agent to use |\n| `--max-iterations \u003cn\u003e` | Max loop iterations (default: 50) |\n\n### Debug Mode\n\nUse `RALPH_DEBUG=1` to see detailed output during execution:\n\n```bash\n# See detailed agent output, timing, and prompts\nRALPH_DEBUG=1 ralph-starter run \"build a todo app\"\n\n# Debug with GitHub issue\nRALPH_DEBUG=1 ralph-starter run --from github --issue 42\n```\n\nDebug mode shows:\n- Exact commands being run\n- Agent output in real-time\n- Timing information\n- Error details\n\n### Workflow Presets\n\n| Flag | Description |\n|------|-------------|\n| `--preset \u003cname\u003e` | Use a workflow preset (feature, tdd-red-green, debug, etc.) |\n\n```bash\n# List all available presets\nralph-starter presets\n\n# Use a preset\nralph-starter run --preset feature \"build login page\"\nralph-starter run --preset tdd-red-green \"add user validation\"\nralph-starter run --preset debug \"fix the auth bug\"\n```\n\n### Exit Detection\n\n| Flag | Description |\n|------|-------------|\n| `--completion-promise \u003cstring\u003e` | Custom string to detect task completion |\n| `--require-exit-signal` | Require explicit `EXIT_SIGNAL: true` for completion |\n\n```bash\n# Stop when agent outputs \"FEATURE_DONE\"\nralph-starter run --completion-promise \"FEATURE_DONE\" \"build X\"\n\n# Require explicit exit signal\nralph-starter run --require-exit-signal \"build Y\"\n```\n\n### Safety Controls\n\n| Flag | Description |\n|------|-------------|\n| `--rate-limit \u003cn\u003e` | Max API calls per hour (default: unlimited) |\n| `--circuit-breaker-failures \u003cn\u003e` | Max consecutive failures before stopping (default: 3) |\n| `--circuit-breaker-errors \u003cn\u003e` | Max same error occurrences before stopping (default: 5) |\n| `--track-progress` | Write progress to activity.md (default: true) |\n| `--no-track-progress` | Disable progress tracking |\n| `--track-cost` | Track token usage and estimated cost (default: true) |\n| `--no-track-cost` | Disable cost tracking |\n\n```bash\n# Limit to 50 API calls per hour\nralph-starter run --rate-limit 50 \"build X\"\n\n# Stop after 2 consecutive failures\nralph-starter run --circuit-breaker-failures 2 \"build Y\"\n```\n\n### Source Options\n\n| Flag | Description |\n|------|-------------|\n| `--from \u003csource\u003e` | Fetch spec from source |\n| `--project \u003cname\u003e` | Project filter for sources |\n| `--label \u003cname\u003e` | Label filter for sources |\n| `--status \u003cstatus\u003e` | Status filter for sources |\n| `--limit \u003cn\u003e` | Max items from source |\n| `--issue \u003cn\u003e` | Specific issue number (GitHub) |\n| `--output-dir \u003cpath\u003e` | Directory to run task in (skips prompt) |\n| `--prd \u003cfile\u003e` | Read tasks from markdown |\n\n## Options for `fix`\n\n| Flag | Description |\n|------|-------------|\n| `--scan` | Force full project scan (build + lint + typecheck + tests) |\n| `--agent \u003cname\u003e` | Specify agent to use (default: auto-detect) |\n| `--commit` | Auto-commit the fix |\n| `--max-iterations \u003cn\u003e` | Max fix iterations (default: 3) |\n| `--output-dir \u003cpath\u003e` | Project directory (default: cwd) |\n\n```bash\n# Fix build/lint errors automatically\nralph-starter fix\n\n# Fix a specific design/visual issue\nralph-starter fix \"fix the paddings and make the colors brighter\"\n\n# Full scan with auto-commit\nralph-starter fix --scan --commit\n```\n\nFor design-related tasks (CSS, colors, spacing, etc.), the fix command automatically:\n- Detects and applies installed design skills\n- Instructs the agent to visually verify changes via browser screenshots\n\n## Config Commands\n\n```bash\n# Set credentials\nralph-starter config set linear.apiKey \u003ckey\u003e\nralph-starter config set notion.token \u003ctoken\u003e\nralph-starter config set github.token \u003ctoken\u003e\n\n# View config\nralph-starter config list\nralph-starter config get linear.apiKey\n\n# Remove\nralph-starter config delete linear.apiKey\n```\n\n## Example: Build a SaaS Dashboard\n\n```bash\nmkdir my-saas \u0026\u0026 cd my-saas\ngit init\n\nralph-starter run \"Create a SaaS dashboard with:\n- User authentication (email/password)\n- Stripe subscription billing\n- Dashboard with usage metrics\n- Dark mode support\" --commit --pr --validate\n\n# Watch the magic happen...\n# Loop 1: Setting up Next.js project...\n# Validation passed\n# Committed: chore: initialize Next.js with TypeScript\n# Loop 2: Adding authentication...\n# ✓ Validation passed\n# ✓ Committed: feat(auth): add NextAuth with email provider\n# ...\n# ✓ Created PR #1: \"Build SaaS dashboard\"\n```\n\n## Testing ralph-starter\n\n### Quick Test (No API Keys)\n\nYou can test ralph-starter with public URLs - no API keys required:\n\n```bash\n# Test with a public GitHub gist or raw markdown\nralph-starter run --from https://raw.githubusercontent.com/multivmlabs/ralph-starter/main/README.md\n\n# Test with GitHub issues (requires gh CLI login)\ngh auth login\nralph-starter run --from github --project multivmlabs/ralph-starter --label \"enhancement\"\n```\n\n### Testing the Wizard\n\n```bash\n# Launch the interactive wizard\nralph-starter\n\n# Or test idea mode\nralph-starter ideas\n```\n\n### Testing with Your Own Specs\n\n```bash\n# Create a simple spec file\necho \"Build a simple counter app with React\" \u003e my-spec.md\n\n# Run with local file\nralph-starter run --from ./my-spec.md\n```\n\n### Verifying Source Connectivity\n\nBefore using an integration, verify it's working:\n\n```bash\n# Check what integrations are available\nralph-starter integrations list\n\n# Test each integration\nralph-starter integrations test github\nralph-starter integrations test linear\nralph-starter integrations test notion\n\n# Preview items (dry run)\nralph-starter integrations fetch linear \"My Project\" --limit 3\n```\n\n## API Key Configuration\n\n### Option 1: Environment Variables (Recommended for Developers)\n\nSet environment variables in your shell profile or `.env` file:\n\n```bash\n# Add to ~/.bashrc, ~/.zshrc, or .env file\nexport LINEAR_API_KEY=lin_api_xxxxx\nexport NOTION_API_KEY=secret_xxxxx\nexport GITHUB_TOKEN=ghp_xxxxx\n```\n\nEnvironment variables take precedence over the config file.\n\n### Option 2: Config Command\n\nUse the CLI to store credentials:\n\n```bash\nralph-starter config set linear.apiKey lin_api_xxxxx\nralph-starter config set notion.token secret_xxxxx\nralph-starter config set github.token ghp_xxxxx\n```\n\nCredentials are stored in `~/.ralph-starter/sources.json`.\n\n### Environment Variable Reference\n\n| Source | Environment Variable | Config Key |\n|--------|---------------------|------------|\n| Linear | `LINEAR_API_KEY` | `linear.apiKey` |\n| Notion | `NOTION_API_KEY` | `notion.token` |\n| GitHub | `GITHUB_TOKEN` | `github.token` |\n| Figma | `FIGMA_TOKEN` | `figma.token` |\n\n## Requirements\n\n- Node.js 18+\n- At least one coding agent installed (Claude Code, Cursor, etc.)\n- Git (for automation features)\n- GitHub CLI `gh` (for PR creation and GitHub source)\n\n## Documentation\n\nFull documentation available at: https://ralphstarter.ai\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- **Feature requests \u0026 ideas**: [ralph-ideas](https://github.com/multivmlabs/ralph-ideas)\n- **Project templates**: [ralph-templates](https://github.com/multivmlabs/ralph-templates)\n\nFor creating custom integrations, agents, or using the programmatic API, see the [Developer Extension Guide](https://ralphstarter.ai/docs/guides/extending-ralph-starter).\n\n## Badge\n\nUsing ralph-starter? Add the badge to your README:\n\n[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)\n\n```markdown\n[![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)\n```\n\nMore styles available at [ralphstarter.ai/badge](https://ralphstarter.ai/badge).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultivmlabs%2Fralph-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultivmlabs%2Fralph-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultivmlabs%2Fralph-starter/lists"}