ralph
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.
Badge for your README
Markdown
[](/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)
- {
- "name": "ralph",
- "owner": {
- "name": "MultiVM Labs",
- "email": "hello@multivmlabs.com"
- },
- "metadata": {
- "description": "Autonomous AI coding loops — fetch specs from GitHub, Linear, Notion, Figma, and OpenSpec, then orchestrate coding agents to build software automatically.",
- "version": "0.4.0"
- },
- "plugins": [
- {
- "name": "ralph-starter",
- "source": "./",
- "description": "Run autonomous AI coding loops with ralph-starter. Orchestrate Claude Code, Cursor, Codex, Gemini CLI, and more to build software from specs automatically.",
- "version": "0.4.0",
- "author": {
- "name": "Ruben Marcus",
- "email": "ruben@rubenmarcus.dev"
- },
- "homepage": "https://ralphstarter.ai",
- "repository": "https://github.com/multivmlabs/ralph-starter",
- "license": "MIT",
- "keywords": [
- "autonomous",
- "coding-loop",
- "orchestrator",
- "figma",
- "linear",
- "github",
- "notion",
- "claude-code",
- "cursor",
- "codex",
- "gemini"
- ],
- "category": "development",
- "tags": [
- "ai-coding",
- "automation",
- "dev-tools",
- "integrations"
- ]
- }
- ]
- }
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)
- <p align="center">
- <img src="ralph.png" alt="Ralph Wiggum" />
- </p>
- <p align="center">
- <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>
- </p>
- <p align="center">
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- </p>
- <h3 align="center">
- <strong>The most complete Ralph Wiggum implementation.<br/>Connect your tools. Run AI coding loops. Ship faster.</strong>
- </h3>
- <p align="center">
- <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>
- </p>
- <p align="center">
- <a href="#integrations">Integrations</a> •
- <a href="#quick-start">Quick Start</a> •
- <a href="#features">Features</a> •
- <a href="https://ralphstarter.ai">Docs</a>
- </p>
- <p align="center">
- <img src="https://ralphstarter.ai/img/demos/figma-demo.gif" alt="ralph-starter Figma demo" width="700" />
- </p>
- ---
- 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 github` | Interactive GitHub issues wizard |
- | `ralph-starter linear` | Interactive Linear issues wizard |
- | `ralph-starter notion` | Interactive Notion pages wizard |
- | `ralph-starter auto` | Batch-process issues from GitHub/Linear |
- | `ralph-starter task <action>` | Manage tasks across GitHub and Linear (list, create, update, close, comment) |
- | `ralph-starter integrations <action>` | Manage integrations (list, help, test, fetch) |
- | `ralph-starter plan` | Create implementation plan from specs |
- | `ralph-starter init` | Initialize Ralph Playbook in a project |
- | `ralph-starter setup` | Configure environment and API keys interactively |
- | `ralph-starter check` | Verify system requirements and connectivity |
- | `ralph-starter ideas` | Brainstorm project ideas |
- | `ralph-starter presets` | List available workflow presets |
- | `ralph-starter mcp` | Start as MCP server |
- | `ralph-starter config <action>` | Manage credentials |
- | `ralph-starter source <action>` | Manage input sources (legacy) |
- | `ralph-starter skill add <repo>` | Install agent skills |
- ## Options for `run`
- ### Core Options
- | Flag | Description |
- |------|-------------|
- | `--auto` | Skip permission prompts **(default: true)** |
- | `--no-auto` | Require manual permission approval |
- | `--commit` | Auto-commit after tasks |
- | `--push` | Push commits to remote |
- | `--pr` | Create pull request |
- | `--validate` | Run tests/lint/build (backpressure) |
- | `--agent <name>` | Specify agent to use |
- | `--max-iterations <n>` | Max loop iterations (default: 50) |
- ### Debug Mode
- Use `RALPH_DEBUG=1` to see detailed output during execution:
- ```bash
- # See detailed agent output, timing, and prompts
- RALPH_DEBUG=1 ralph-starter run "build a todo app"
- # Debug with GitHub issue
- RALPH_DEBUG=1 ralph-starter run --from github --issue 42
- ```
- Debug mode shows:
- - Exact commands being run
- - Agent output in real-time
- - Timing information
- - Error details
- ### Workflow Presets
- | Flag | Description |
- |------|-------------|
- | `--preset <name>` | Use a workflow preset (feature, tdd-red-green, debug, etc.) |
- ```bash
- # List all available presets
- ralph-starter presets
- # Use a preset
- ralph-starter run --preset feature "build login page"
- ralph-starter run --preset tdd-red-green "add user validation"
- ralph-starter run --preset debug "fix the auth bug"
- ```
- ### Exit Detection
- | Flag | Description |
- |------|-------------|
- | `--completion-promise <string>` | Custom string to detect task completion |
- | `--require-exit-signal` | Require explicit `EXIT_SIGNAL: true` for completion |
- ```bash
- # Stop when agent outputs "FEATURE_DONE"
- ralph-starter run --completion-promise "FEATURE_DONE" "build X"
- # Require explicit exit signal
- ralph-starter run --require-exit-signal "build Y"
- ```
- ### Safety Controls
- | Flag | Description |
- |------|-------------|
- | `--rate-limit <n>` | Max API calls per hour (default: unlimited) |
- | `--circuit-breaker-failures <n>` | Max consecutive failures before stopping (default: 3) |
- | `--circuit-breaker-errors <n>` | Max same error occurrences before stopping (default: 5) |
- | `--track-progress` | Write progress to activity.md (default: true) |
- | `--no-track-progress` | Disable progress tracking |
- | `--track-cost` | Track token usage and estimated cost (default: true) |
- | `--no-track-cost` | Disable cost tracking |
- ```bash
- # Limit to 50 API calls per hour
- ralph-starter run --rate-limit 50 "build X"
- # Stop after 2 consecutive failures
- ralph-starter run --circuit-breaker-failures 2 "build Y"
- ```
- ### Source Options
- | Flag | Description |
- |------|-------------|
- | `--from <source>` | Fetch spec from source |
- | `--project <name>` | Project filter for sources |
- | `--label <name>` | Label filter for sources |
- | `--status <status>` | Status filter for sources |
- | `--limit <n>` | Max items from source |
- | `--issue <n>` | Specific issue number (GitHub) |
- | `--output-dir <path>` | Directory to run task in (skips prompt) |
- | `--prd <file>` | Read tasks from markdown |
- ## Options for `fix`
- | Flag | Description |
- |------|-------------|
- | `--scan` | Force full project scan (build + lint + typecheck + tests) |
- | `--agent <name>` | Specify agent to use (default: auto-detect) |
- | `--commit` | Auto-commit the fix |
- | `--max-iterations <n>` | Max fix iterations (default: 3) |
- | `--output-dir <path>` | Project directory (default: cwd) |
- ```bash
- # Fix build/lint errors automatically
- ralph-starter fix
- # Fix a specific design/visual issue
- ralph-starter fix "fix the paddings and make the colors brighter"
- # Full scan with auto-commit
- ralph-starter fix --scan --commit
- ```
- For design-related tasks (CSS, colors, spacing, etc.), the fix command automatically:
- - Detects and applies installed design skills
- - Instructs the agent to visually verify changes via browser screenshots
- ## Config Commands
- ```bash
- # Set credentials
- ralph-starter config set linear.apiKey <key>
- ralph-starter config set notion.token <token>
- ralph-starter config set github.token <token>
- # View config
- ralph-starter config list
- ralph-starter config get linear.apiKey
- # Remove
- ralph-starter config delete linear.apiKey
- ```
- ## Example: Build a SaaS Dashboard
- ```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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.