Skip to content
Back to search

ralph

MarketplaceWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rubenmarcus--ralph-starter/badge.svg)](/listings/rubenmarcus--ralph-starter)

HTML

<a href="/listings/rubenmarcus--ralph-starter"><img src="/api/listings/rubenmarcus--ralph-starter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 46 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ralph",
  3. "owner": {
  4. "name": "MultiVM Labs",
  5. "email": "hello@multivmlabs.com"
  6. },
  7. "metadata": {
  8. "description": "Autonomous AI coding loops — fetch specs from GitHub, Linear, Notion, Figma, and OpenSpec, then orchestrate coding agents to build software automatically.",
  9. "version": "0.4.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "ralph-starter",
  14. "source": "./",
  15. "description": "Run autonomous AI coding loops with ralph-starter. Orchestrate Claude Code, Cursor, Codex, Gemini CLI, and more to build software from specs automatically.",
  16. "version": "0.4.0",
  17. "author": {
  18. "name": "Ruben Marcus",
  19. "email": "ruben@rubenmarcus.dev"
  20. },
  21. "homepage": "https://ralphstarter.ai",
  22. "repository": "https://github.com/multivmlabs/ralph-starter",
  23. "license": "MIT",
  24. "keywords": [
  25. "autonomous",
  26. "coding-loop",
  27. "orchestrator",
  28. "figma",
  29. "linear",
  30. "github",
  31. "notion",
  32. "claude-code",
  33. "cursor",
  34. "codex",
  35. "gemini"
  36. ],
  37. "category": "development",
  38. "tags": [
  39. "ai-coding",
  40. "automation",
  41. "dev-tools",
  42. "integrations"
  43. ]
  44. }
  45. ]
  46. }
README.md · README · 772 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="ralph.png" alt="Ralph Wiggum" />
  3. </p>
  4. <p align="center">
  5. <a href="https://ralphstarter.ai/badge"><img src="https://ralphstarter.ai/img/badge-built-with@2x.png" alt="built with ralph-starter" height="28"></a>
  6. </p>
  7. <p align="center">
  8. <a href="https://www.npmjs.com/package/ralph-starter"><img src="https://img.shields.io/npm/v/ralph-starter.svg?style=flat-square" alt="npm version"></a>
  9. <a href="https://www.npmjs.com/package/ralph-starter"><img src="https://img.shields.io/npm/dm/ralph-starter.svg?style=flat-square" alt="npm downloads"></a>
  10. <a href="https://github.com/multivmlabs/ralph-starter/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/ralph-starter.svg?style=flat-square" alt="license"></a>
  11. <a href="https://github.com/multivmlabs/ralph-starter/actions"><img src="https://img.shields.io/github/actions/workflow/status/multivmlabs/ralph-starter/ci.yml?branch=main&style=flat-square" alt="build status"></a>
  12. <a href="https://github.com/multivmlabs/ralph-starter/actions/workflows/security.yml"><img src="https://img.shields.io/github/actions/workflow/status/multivmlabs/ralph-starter/security.yml?branch=main&style=flat-square&label=security" alt="security scanning"></a>
  13. <a href="https://securityscorecards.dev/viewer/?uri=github.com/multivmlabs/ralph-starter"><img src="https://img.shields.io/ossf-scorecard/github.com/multivmlabs/ralph-starter?style=flat-square&label=scorecard" alt="OSSF Scorecard"></a>
  14. <a href="https://github.com/multivmlabs/ralph-starter"><img src="https://img.shields.io/github/stars/multivmlabs/ralph-starter?style=flat-square" alt="GitHub stars"></a>
  15. </p>
  16. <h3 align="center">
  17. <strong>The most complete Ralph Wiggum implementation.<br/>Connect your tools. Run AI coding loops. Ship faster.</strong>
  18. </h3>
  19. <p align="center">
  20. <em>The easiest way to run Ralph Wiggum autonomous coding loops — pull specs from GitHub, Linear, Notion, Figma, and more, then let AI build it.</em>
  21. </p>
  22. <p align="center">
  23. <a href="#integrations">Integrations</a> •
  24. <a href="#quick-start">Quick Start</a> •
  25. <a href="#features">Features</a> •
  26. <a href="https://ralphstarter.ai">Docs</a>
  27. </p>
  28. <p align="center">
  29. <img src="https://ralphstarter.ai/img/demos/figma-demo.gif" alt="ralph-starter Figma demo" width="700" />
  30. </p>
  31. ---
  32. Most AI coding tools work in isolation. You describe a task, AI builds it, done.
  33. **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.
  34. ```bash
  35. # Build from a GitHub issue
  36. ralph-starter run --from github --project myorg/myrepo --label "ready"
  37. # Build from a Linear ticket
  38. ralph-starter run --from linear --project "Mobile App" --label "sprint-1"
  39. # Build from a Notion spec
  40. ralph-starter run --from notion --project "https://notion.so/Product-Spec-abc123"
  41. # Or just describe what you want
  42. ralph-starter run "build a todo app with React" --commit
  43. ```
  44. ---
  45. ## Integrations
  46. ralph-starter integrates with your favorite tools out of the box:
  47. | Integration | Auth Method | What It Fetches |
  48. |-------------|-------------|-----------------|
  49. | **GitHub** | `gh` CLI (recommended) or API token | Issues, PRs, files |
  50. | **Linear** | `linear` CLI or API key | Issues by team/project |
  51. | **Notion** | None (public) or API token (private) | Pages, databases |
  52. | **Figma** | API token | Design specs, tokens, assets & content extraction |
  53. | **URLs** | None | Any public markdown/HTML |
  54. | **Files** | None | Local markdown, PDF |
  55. ```bash
  56. # Check available integrations
  57. ralph-starter integrations list
  58. # Test connectivity
  59. ralph-starter integrations test github
  60. ralph-starter integrations test linear
  61. # Preview data before running
  62. ralph-starter integrations fetch github owner/repo
  63. ```
  64. > **Want more integrations?** PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
  65. ---
  66. ## Table of Contents
  67. - [Integrations](#integrations)
  68. - [Quick Start](#quick-start)
  69. - [Features](#features)
  70. - [Commands](#commands)
  71. - [Configuration](#api-key-configuration)
  72. - [Contributing](#contributing)
  73. ---
  74. ### Key Features
  75. | Feature | Description |
  76. |---------|-------------|
  77. | **Integrations** | Pull specs from GitHub, Linear, Notion, Figma, URLs, files |
  78. | **Multi-Agent Support** | Works with Claude Code, Cursor, Copilot, Gemini CLI, and more |
  79. | **Interactive Wizard** | Guided project creation with AI-refined specifications |
  80. | **16+ Workflow Presets** | Pre-configured modes: feature, tdd, debug, review, and more |
  81. | **Circuit Breaker** | Auto-stops stuck loops after repeated failures |
  82. | **Cost Tracking** | Estimates token usage and cost per iteration |
  83. | **Git Automation** | Auto-commit, push, and PR creation |
  84. | **Backpressure Validation** | Run tests/lint/build after each iteration |
  85. | **MCP Server** | Use from Claude Desktop or any MCP client |
  86. ### Quick Example
  87. ```bash
  88. # Simple task
  89. ralph-starter run "build a todo app" --commit --validate
  90. # With preset
  91. ralph-starter run --preset tdd-red-green "add user authentication"
  92. # With safety controls
  93. ralph-starter run --rate-limit 50 --circuit-breaker-failures 3 "build X"
  94. # Interactive wizard
  95. ralph-starter
  96. ```
  97. ---
  98. ## What is Ralph Wiggum?
  99. 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.
  100. **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.
  101. **Why ralph-starter over a raw Ralph Wiggum script?**
  102. - **Spec-driven**: Pull tasks from GitHub, Linear, Notion, Figma — not just manual prompts
  103. - **Safe**: Circuit breakers stop stuck loops, rate limiters control costs
  104. - **Multi-agent**: Works with 8+ coding agents, not just one
  105. - **Observable**: Cost tracking, progress logs, iteration history
  106. - **Automated**: Auto-commit, push, and PR creation built in
  107. ## Installation
  108. ```bash
  109. npm install -g ralph-starter
  110. # or
  111. npx ralph-starter
  112. ```
  113. After installing, run the setup wizard and verify your environment:
  114. ```bash
  115. ralph-starter setup # Configure API keys and preferences
  116. ralph-starter check # Verify system requirements and connectivity
  117. ```
  118. ## Quick Start
  119. ### For Everyone (Non-Developers Welcome!)
  120. Just run `ralph-starter` with no arguments to launch the interactive wizard:
  121. ```bash
  122. ralph-starter
  123. ```
  124. The wizard will:
  125. 1. Ask if you have a project idea (or help you brainstorm one)
  126. 2. Refine your idea with AI
  127. 3. Let you customize the tech stack
  128. 4. Build your project automatically
  129. ### Don't Know What to Build?
  130. ```bash
  131. ralph-starter ideas
  132. ```
  133. This launches **Idea Mode** - a brainstorming session to help you discover project ideas:
  134. - **Brainstorm with AI** - Get creative suggestions
  135. - **See trending ideas** - Based on 2025-2026 tech trends
  136. - **Based on my skills** - Personalized to technologies you know
  137. - **Solve a problem** - Help fix something that frustrates you
  138. ### For Developers
  139. ```bash
  140. # Run a single task
  141. ralph-starter run "build a todo app with React"
  142. # With git automation
  143. ralph-starter run "add user authentication" --commit --pr
  144. # With validation (backpressure)
  145. ralph-starter run "refactor auth" --commit --validate
  146. # Fetch specs from external sources
  147. ralph-starter run --from https://example.com/spec.md
  148. ralph-starter run --from github --project myorg/myrepo --label "ready"
  149. ralph-starter run --from linear --project "Mobile App"
  150. # Fetch a specific GitHub issue
  151. ralph-starter run --from github --project owner/repo --issue 123
  152. # Specify output directory (skips "where to run?" prompt)
  153. ralph-starter run --from github --project owner/repo --issue 42 --output-dir ~/projects/new-app
  154. ```
  155. ### Working with Existing Projects
  156. ralph-starter automatically detects existing projects when you run the wizard:
  157. **Ralph Playbook Project** (has AGENTS.md, IMPLEMENTATION_PLAN.md, etc.):
  158. ```bash
  159. cd my-ralph-project
  160. ralph-starter
  161. ```
  162. The wizard will detect the Ralph Playbook files and let you:
  163. - Continue working (run the build loop)
  164. - Regenerate the implementation plan
  165. - Add new specs
  166. **Language Project** (has package.json, pyproject.toml, Cargo.toml, go.mod):
  167. ```bash
  168. cd my-existing-app
  169. ralph-starter
  170. ```
  171. The wizard will detect the project type and let you:
  172. - Add features to the existing project
  173. - Create a new project in a subfolder
  174. ## Features
  175. ### Interactive Wizard
  176. Launch with `ralph-starter` (no args) for a guided experience:
  177. - Describe your idea in plain English
  178. - AI refines and suggests features
  179. - Choose your tech stack
  180. - Auto-runs init → plan → build
  181. ### Idea Mode
  182. For users who don't know what to build yet:
  183. ```bash
  184. ralph-starter ideas
  185. ```
  186. ### MCP Server
  187. Use ralph-starter from Claude Desktop or any MCP client:
  188. ```bash
  189. ralph-starter mcp
  190. ```
  191. Add to Claude Desktop config:
  192. ```json
  193. {
  194. "mcpServers": {
  195. "ralph-starter": {
  196. "command": "ralph-starter",
  197. "args": ["mcp"]
  198. }
  199. }
  200. }
  201. ```
  202. **Available MCP Tools:**
  203. - `ralph_init` - Initialize Ralph Playbook
  204. - `ralph_plan` - Create implementation plan
  205. - `ralph_run` - Execute coding loop
  206. - `ralph_status` - Check progress
  207. - `ralph_validate` - Run tests/lint/build
  208. ### Multi-Agent Support
  209. Works with your favorite coding agents:
  210. - **Claude Code** (recommended)
  211. - **Cursor**
  212. - **OpenCode**
  213. - **OpenAI Codex**
  214. - **GitHub Copilot**
  215. - **Gemini CLI**
  216. - **Amp**
  217. - **Openclaw**
  218. ### LLM Providers
  219. ralph-starter supports multiple LLM providers for internal features:
  220. | Provider | Environment Variable | Description |
  221. |----------|---------------------|-------------|
  222. | **Anthropic** | `ANTHROPIC_API_KEY` | Claude models (default) |
  223. | **OpenAI** | `OPENAI_API_KEY` | GPT-4 and GPT-4o |
  224. | **OpenRouter** | `OPENROUTER_API_KEY` | 100+ models with one API |
  225. These keys are for ralph-starter's internal LLM calls. Coding agents handle their own authentication.
  226. ### Git Automation
  227. ```bash
  228. ralph-starter run "your task" --commit # Auto-commit after tasks
  229. ralph-starter run "your task" --push # Push to remote
  230. ralph-starter run "your task" --pr # Create PR when done
  231. ```
  232. ### Backpressure Validation
  233. ```bash
  234. ralph-starter run "your task" --validate # Run tests/lint/build after each iteration
  235. ```
  236. 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.
  237. ### Workflow Presets
  238. Pre-configured settings for common development scenarios:
  239. ```bash
  240. # List all 16+ presets
  241. ralph-starter presets
  242. # Use a preset
  243. ralph-starter run --preset feature "build login"
  244. ralph-starter run --preset tdd-red-green "add tests"
  245. ralph-starter run --preset debug "fix the bug"
  246. ralph-starter run --preset refactor "clean up auth module"
  247. ralph-starter run --preset pr-review "review changes"
  248. ```
  249. **Available Presets:**
  250. | Category | Presets |
  251. |----------|---------|
  252. | Development | `feature`, `feature-minimal`, `tdd-red-green`, `spec-driven`, `refactor` |
  253. | Debugging | `debug`, `incident-response`, `code-archaeology` |
  254. | Review | `review`, `pr-review`, `adversarial-review` |
  255. | Documentation | `docs`, `documentation-first` |
  256. | Specialized | `api-design`, `migration-safety`, `performance-optimization`, `scientific-method`, `research`, `gap-analysis` |
  257. ### Circuit Breaker
  258. Automatically stops loops that are stuck:
  259. ```bash
  260. # Stop after 3 consecutive failures (default)
  261. ralph-starter run "build X" --validate
  262. # Custom thresholds
  263. ralph-starter run "build X" --circuit-breaker-failures 2 --circuit-breaker-errors 3
  264. ```
  265. The circuit breaker monitors:
  266. - **Consecutive failures**: Stops after N validation failures in a row
  267. - **Same error count**: Stops if the same error repeats N times
  268. ### Progress Tracking
  269. Writes iteration logs to `activity.md`:
  270. ```bash
  271. # Enabled by default
  272. ralph-starter run "build X"
  273. # Disable if not needed
  274. ralph-starter run "build X" --no-track-progress
  275. ```
  276. Each iteration records:
  277. - Timestamp and duration
  278. - Status (completed, failed, blocked)
  279. - Validation results
  280. - Commit info
  281. ### File-Based Completion
  282. The loop automatically checks for completion signals:
  283. - `RALPH_COMPLETE` file in project root
  284. - `.ralph-done` marker file
  285. - All tasks marked `[x]` in `IMPLEMENTATION_PLAN.md`
  286. ### Rate Limiting
  287. Control API call frequency to manage costs:
  288. ```bash
  289. # Limit to 50 calls per hour
  290. ralph-starter run --rate-limit 50 "build X"
  291. ```
  292. **When rate limits are reached**, ralph-starter displays detailed stats:
  293. ```
  294. ⚠ Claude rate limit reached
  295. Rate Limit Stats:
  296. • Session usage: 100% (50K / 50K tokens)
  297. • Requests made: 127 this hour
  298. • Time until reset: ~47 minutes (resets at 04:30 UTC)
  299. Session Progress:
  300. • Tasks completed: 3/5
  301. • Current task: "Add swarm mode CLI flags"
  302. • Branch: auto/github-54
  303. • Iterations completed: 12
  304. To resume when limit resets:
  305. ralph-starter run
  306. Tip: Check your limits at https://claude.ai/settings
  307. ```
  308. This helps you:
  309. - Know exactly when you can resume
  310. - Track progress on your current session
  311. - Understand your usage patterns
  312. ### Cost Tracking
  313. Track estimated token usage and costs during loops:
  314. ```bash
  315. # Cost tracking is enabled by default
  316. ralph-starter run "build X"
  317. # Disable cost tracking
  318. ralph-starter run "build X" --no-track-cost
  319. ```
  320. Cost tracking provides:
  321. - **Per-iteration cost** displayed during the loop
  322. - **Running total** of tokens and cost
  323. - **Cost summary** at the end of the loop
  324. - **Cost logged** in `activity.md` for each iteration
  325. - **Projected cost** for remaining iterations (after 3+ iterations)
  326. Supported models for cost estimation:
  327. - Claude 3 Opus ($15/$75 per 1M tokens)
  328. - Claude 3.5 Sonnet ($3/$15 per 1M tokens)
  329. - Claude 3.5 Haiku ($0.25/$1.25 per 1M tokens)
  330. - GPT-4 ($30/$60 per 1M tokens)
  331. - GPT-4 Turbo ($10/$30 per 1M tokens)
  332. ## Ralph Playbook Workflow
  333. ralph-starter follows the [Ralph Playbook](https://claytonfarr.github.io/ralph-playbook/) methodology:
  334. ```bash
  335. # 1. Initialize Ralph Playbook files
  336. ralph-starter init
  337. # 2. Write specs in specs/ folder
  338. # 3. Create implementation plan
  339. ralph-starter plan
  340. # 4. Execute the plan
  341. ralph-starter run --commit --validate
  342. ```
  343. This creates:
  344. - `AGENTS.md` - Agent instructions and validation commands
  345. - `PROMPT_plan.md` - Planning prompt template
  346. - `PROMPT_build.md` - Building prompt template
  347. - `IMPLEMENTATION_PLAN.md` - Prioritized task list
  348. - `specs/` - Specification files
  349. ## Commands
  350. | Command | Description |
  351. |---------|-------------|
  352. | `ralph-starter` | Launch interactive wizard |
  353. | `ralph-starter run [task]` | Run an autonomous coding loop |
  354. | `ralph-starter fix [task]` | Fix build errors, lint issues, or design problems |
  355. | `ralph-starter github` | Interactive GitHub issues wizard |
  356. | `ralph-starter linear` | Interactive Linear issues wizard |
  357. | `ralph-starter notion` | Interactive Notion pages wizard |
  358. | `ralph-starter auto` | Batch-process issues from GitHub/Linear |
  359. | `ralph-starter task <action>` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |
  360. | `ralph-starter integrations <action>` | Manage integrations (list, help, test, fetch) |
  361. | `ralph-starter plan` | Create implementation plan from specs |
  362. | `ralph-starter init` | Initialize Ralph Playbook in a project |
  363. | `ralph-starter setup` | Configure environment and API keys interactively |
  364. | `ralph-starter check` | Verify system requirements and connectivity |
  365. | `ralph-starter ideas` | Brainstorm project ideas |
  366. | `ralph-starter presets` | List available workflow presets |
  367. | `ralph-starter mcp` | Start as MCP server |
  368. | `ralph-starter config <action>` | Manage credentials |
  369. | `ralph-starter source <action>` | Manage input sources (legacy) |
  370. | `ralph-starter skill add <repo>` | Install agent skills |
  371. ## Options for `run`
  372. ### Core Options
  373. | Flag | Description |
  374. |------|-------------|
  375. | `--auto` | Skip permission prompts **(default: true)** |
  376. | `--no-auto` | Require manual permission approval |
  377. | `--commit` | Auto-commit after tasks |
  378. | `--push` | Push commits to remote |
  379. | `--pr` | Create pull request |
  380. | `--validate` | Run tests/lint/build (backpressure) |
  381. | `--agent <name>` | Specify agent to use |
  382. | `--max-iterations <n>` | Max loop iterations (default: 50) |
  383. ### Debug Mode
  384. Use `RALPH_DEBUG=1` to see detailed output during execution:
  385. ```bash
  386. # See detailed agent output, timing, and prompts
  387. RALPH_DEBUG=1 ralph-starter run "build a todo app"
  388. # Debug with GitHub issue
  389. RALPH_DEBUG=1 ralph-starter run --from github --issue 42
  390. ```
  391. Debug mode shows:
  392. - Exact commands being run
  393. - Agent output in real-time
  394. - Timing information
  395. - Error details
  396. ### Workflow Presets
  397. | Flag | Description |
  398. |------|-------------|
  399. | `--preset <name>` | Use a workflow preset (feature, tdd-red-green, debug, etc.) |
  400. ```bash
  401. # List all available presets
  402. ralph-starter presets
  403. # Use a preset
  404. ralph-starter run --preset feature "build login page"
  405. ralph-starter run --preset tdd-red-green "add user validation"
  406. ralph-starter run --preset debug "fix the auth bug"
  407. ```
  408. ### Exit Detection
  409. | Flag | Description |
  410. |------|-------------|
  411. | `--completion-promise <string>` | Custom string to detect task completion |
  412. | `--require-exit-signal` | Require explicit `EXIT_SIGNAL: true` for completion |
  413. ```bash
  414. # Stop when agent outputs "FEATURE_DONE"
  415. ralph-starter run --completion-promise "FEATURE_DONE" "build X"
  416. # Require explicit exit signal
  417. ralph-starter run --require-exit-signal "build Y"
  418. ```
  419. ### Safety Controls
  420. | Flag | Description |
  421. |------|-------------|
  422. | `--rate-limit <n>` | Max API calls per hour (default: unlimited) |
  423. | `--circuit-breaker-failures <n>` | Max consecutive failures before stopping (default: 3) |
  424. | `--circuit-breaker-errors <n>` | Max same error occurrences before stopping (default: 5) |
  425. | `--track-progress` | Write progress to activity.md (default: true) |
  426. | `--no-track-progress` | Disable progress tracking |
  427. | `--track-cost` | Track token usage and estimated cost (default: true) |
  428. | `--no-track-cost` | Disable cost tracking |
  429. ```bash
  430. # Limit to 50 API calls per hour
  431. ralph-starter run --rate-limit 50 "build X"
  432. # Stop after 2 consecutive failures
  433. ralph-starter run --circuit-breaker-failures 2 "build Y"
  434. ```
  435. ### Source Options
  436. | Flag | Description |
  437. |------|-------------|
  438. | `--from <source>` | Fetch spec from source |
  439. | `--project <name>` | Project filter for sources |
  440. | `--label <name>` | Label filter for sources |
  441. | `--status <status>` | Status filter for sources |
  442. | `--limit <n>` | Max items from source |
  443. | `--issue <n>` | Specific issue number (GitHub) |
  444. | `--output-dir <path>` | Directory to run task in (skips prompt) |
  445. | `--prd <file>` | Read tasks from markdown |
  446. ## Options for `fix`
  447. | Flag | Description |
  448. |------|-------------|
  449. | `--scan` | Force full project scan (build + lint + typecheck + tests) |
  450. | `--agent <name>` | Specify agent to use (default: auto-detect) |
  451. | `--commit` | Auto-commit the fix |
  452. | `--max-iterations <n>` | Max fix iterations (default: 3) |
  453. | `--output-dir <path>` | Project directory (default: cwd) |
  454. ```bash
  455. # Fix build/lint errors automatically
  456. ralph-starter fix
  457. # Fix a specific design/visual issue
  458. ralph-starter fix "fix the paddings and make the colors brighter"
  459. # Full scan with auto-commit
  460. ralph-starter fix --scan --commit
  461. ```
  462. For design-related tasks (CSS, colors, spacing, etc.), the fix command automatically:
  463. - Detects and applies installed design skills
  464. - Instructs the agent to visually verify changes via browser screenshots
  465. ## Config Commands
  466. ```bash
  467. # Set credentials
  468. ralph-starter config set linear.apiKey <key>
  469. ralph-starter config set notion.token <token>
  470. ralph-starter config set github.token <token>
  471. # View config
  472. ralph-starter config list
  473. ralph-starter config get linear.apiKey
  474. # Remove
  475. ralph-starter config delete linear.apiKey
  476. ```
  477. ## Example: Build a SaaS Dashboard
  478. ```bash
  479. mkdir my-saas && cd my-saas
  480. git init
  481. ralph-starter run "Create a SaaS dashboard with:
  482. - User authentication (email/password)
  483. - Stripe subscription billing
  484. - Dashboard with usage metrics
  485. - Dark mode support" --commit --pr --validate
  486. # Watch the magic happen...
  487. # Loop 1: Setting up Next.js project...
  488. # Validation passed
  489. # Committed: chore: initialize Next.js with TypeScript
  490. # Loop 2: Adding authentication...
  491. # ✓ Validation passed
  492. # ✓ Committed: feat(auth): add NextAuth with email provider
  493. # ...
  494. # ✓ Created PR #1: "Build SaaS dashboard"
  495. ```
  496. ## Testing ralph-starter
  497. ### Quick Test (No API Keys)
  498. You can test ralph-starter with public URLs - no API keys required:
  499. ```bash
  500. # Test with a public GitHub gist or raw markdown
  501. ralph-starter run --from https://raw.githubusercontent.com/multivmlabs/ralph-starter/main/README.md
  502. # Test with GitHub issues (requires gh CLI login)
  503. gh auth login
  504. ralph-starter run --from github --project multivmlabs/ralph-starter --label "enhancement"
  505. ```
  506. ### Testing the Wizard
  507. ```bash
  508. # Launch the interactive wizard
  509. ralph-starter
  510. # Or test idea mode
  511. ralph-starter ideas
  512. ```
  513. ### Testing with Your Own Specs
  514. ```bash
  515. # Create a simple spec file
  516. echo "Build a simple counter app with React" > my-spec.md
  517. # Run with local file
  518. ralph-starter run --from ./my-spec.md
  519. ```
  520. ### Verifying Source Connectivity
  521. Before using an integration, verify it's working:
  522. ```bash
  523. # Check what integrations are available
  524. ralph-starter integrations list
  525. # Test each integration
  526. ralph-starter integrations test github
  527. ralph-starter integrations test linear
  528. ralph-starter integrations test notion
  529. # Preview items (dry run)
  530. ralph-starter integrations fetch linear "My Project" --limit 3
  531. ```
  532. ## API Key Configuration
  533. ### Option 1: Environment Variables (Recommended for Developers)
  534. Set environment variables in your shell profile or `.env` file:
  535. ```bash
  536. # Add to ~/.bashrc, ~/.zshrc, or .env file
  537. export LINEAR_API_KEY=lin_api_xxxxx
  538. export NOTION_API_KEY=secret_xxxxx
  539. export GITHUB_TOKEN=ghp_xxxxx
  540. ```
  541. Environment variables take precedence over the config file.
  542. ### Option 2: Config Command
  543. Use the CLI to store credentials:
  544. ```bash
  545. ralph-starter config set linear.apiKey lin_api_xxxxx
  546. ralph-starter config set notion.token secret_xxxxx
  547. ralph-starter config set github.token ghp_xxxxx
  548. ```
  549. Credentials are stored in `~/.ralph-starter/sources.json`.
  550. ### Environment Variable Reference
  551. | Source | Environment Variable | Config Key |
  552. |--------|---------------------|------------|
  553. | Linear | `LINEAR_API_KEY` | `linear.apiKey` |
  554. | Notion | `NOTION_API_KEY` | `notion.token` |
  555. | GitHub | `GITHUB_TOKEN` | `github.token` |
  556. | Figma | `FIGMA_TOKEN` | `figma.token` |
  557. ## Requirements
  558. - Node.js 18+
  559. - At least one coding agent installed (Claude Code, Cursor, etc.)
  560. - Git (for automation features)
  561. - GitHub CLI `gh` (for PR creation and GitHub source)
  562. ## Documentation
  563. Full documentation available at: https://ralphstarter.ai
  564. ## Contributing
  565. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  566. - **Feature requests & ideas**: [ralph-ideas](https://github.com/multivmlabs/ralph-ideas)
  567. - **Project templates**: [ralph-templates](https://github.com/multivmlabs/ralph-templates)
  568. For creating custom integrations, agents, or using the programmatic API, see the [Developer Extension Guide](https://ralphstarter.ai/docs/guides/extending-ralph-starter).
  569. ## Badge
  570. Using ralph-starter? Add the badge to your README:
  571. [![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)
  572. ```markdown
  573. [![built with ralph-starter](https://ralphstarter.ai/img/badge-built-with@2x.png)](https://github.com/multivmlabs/ralph-starter)
  574. ```
  575. More styles available at [ralphstarter.ai/badge](https://ralphstarter.ai/badge).
  576. ## License
  577. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.