![\"Stirrup](\"./docs/stirrup-infographic.png\")
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/stirrup-ai?style=flat-square&color=0ea5e9\")
![\"license\"](\"https://img.shields.io/github/license/PrincipalForce/stirrup?style=flat-square&color=22c55e\")
![\"node](\"https://img.shields.io/badge/node-%3E%3D20-417e38?style=flat-square\"){kind=icon}
![\"tests\"](\"https://img.shields.io/badge/tests-48%20passing-22c55e?style=flat-square\"){kind=icon}
![\"typescript\"](\"https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square\"){kind=icon}
\nBuild, visualize, and execute AI-powered automation pipelines with a visual node editor.
\nConnect LLMs, code generators, APIs, and integrations into production-ready workflows.\n
\n 35 Templates • 8 Core + 83 Plugin Node Types • 18 Plugins • CLI + UI\n
\n\n```bash\nnpm install -g stirrup-ai\n```\n\n---\n\n## Powerful Node Types\n\nMix AI and deterministic nodes to build workflows that think, fetch, branch, and deploy.\n\n| | Type | What it does |\n|---|---|---|\n| **AI** | `llm-prompt` | Send a templated prompt to Claude or Gemini, get text or structured JSON back |\n| **AI** | `code-generation` | AI writes code in JS/TS/Python, optionally executes it in a sandbox |\n| **AI** | `decision-routing` | AI evaluates data and picks the next branch from labeled options |\n| **AI** | `agent-tool-use` | Autonomous agent with access to registered tools in a loop |\n| **Deterministic** | `transform` | Evaluate a JavaScript expression on inputs |\n| **Deterministic** | `condition` | Branch the workflow based on an expression result |\n| **Deterministic** | `http` | Make HTTP requests to any API |\n| **Deterministic** | `script` | Run JavaScript in a sandboxed VM with fetch, URL, and await support |\n\nPlus 83 plugin node types: GitHub PRs/issues/repos, Slack messages, LinkedIn posts, Launchmatic deploys, Replicate image gen, git clone/branch/push, file scaffold, and more. All extensible through the [plugin system](#plugins).\n\n---\n\n## Why Stirrup?\n\n### Visual Node Editor\nBuild workflows by dragging nodes onto a canvas, connecting them, and configuring each one with purpose-built form editors. No code required to get started.\n\n### Multi-Model AI (Claude + Gemini)\nEvery AI node works with Claude or Gemini. Set `model: claude-sonnet-4-...` or `model: gemini-2.5-flash` on any node — Stirrup routes to the right provider automatically based on the model prefix. Mix both in the same workflow to optimize for cost, speed, or capability per step.\n\n### AI Generate\nDescribe what you want in plain English and Claude generates the complete workflow with nodes, connections, and configuration automatically.\n\n### 35 Templates\nBattle-tested templates for software development, DevOps, marketing, content, and operations. Highlights:\n\n- **Dark Factory** — full-lifecycle enterprise software generation with multi-pass code gen, quality gates, and git delivery\n- **Repo Momma** — nurturing repo improvement: measure twice, cut once, PR with care\n- **Brownfield Mode** — analyze existing repos, generate fixes, open PRs, deploy previews\n- Plus: PR reviews, deployment pipelines, LinkedIn posting, content repurposing, competitor monitoring, SEO briefs, and more\n\n### Live Execution Monitor\nWatch your workflow execute with real-time status updates. Nodes light up as they run, show timing, and display output data inline on the canvas.\n\n### Debug & Inspect\nWhen a node fails, click it to see the exact error, resolved inputs, and stack trace. Click **Analyze with AI** and Claude diagnoses the issue and suggests concrete field edits you can apply with one click.\n\n### Resume After Failure\nEvery execution is persisted to SQLite. When a workflow fails, hit **Resume** — completed nodes stay done, the failed node retries, and the rest of the DAG continues from where it stopped. Reload the page and your last execution is automatically restored so nothing is lost.\n\n### Params & Connections\nDefine typed workflow parameters with service bindings for auto-injected credentials and smart UI controls like the GitHub repo picker. Connect once, use everywhere.\n\n### Interactive Tutorial\nFirst-time users get a 15-step guided walkthrough that highlights each feature with a spotlight overlay and opens the real panels at each step. Reopenable anytime from the **?** button.\n\n---\n\n## Quick Start\n\n```bash\n# Install globally\nnpm install -g stirrup-ai\n\n# Set your Anthropic API key (or use Gemini — see below)\nstirrup config set anthropicApiKey sk-ant-...\n# Optional: add Gemini for gemini-* models\n# export GEMINI_API_KEY=AIza...\n\n# Launch the visual editor\nstirrup ui\n\n# Or create a workflow from a template via CLI\nstirrup init\n\n# Run with parameters\nstirrup run workflows/pr-review.yaml \\\n --set repo=myorg/myrepo \\\n --set prNumber=42\n```\n\n---\n\n## How It Works\n\nWorkflows are YAML files that describe a directed acyclic graph. Each node is either deterministic or AI-powered. The engine executes them as a parallel DAG — independent nodes run concurrently, conditional branches are evaluated at runtime, and every step's state is persisted to SQLite.\n\n```yaml\nid: review-pipeline\nname: Automated Code Review\nversion: \"1.0\"\n\nparams:\n - name: repo\n type: string\n required: true\n picker: github-repo\n - name: prNumber\n type: number\n required: true\n - name: githubToken\n type: string\n service: github\n\nnodes:\n - id: fetch-diff\n type: http\n name: Fetch PR Diff\n inputs:\n - from: context.repo\n to: repo\n config:\n url: \"https://api.github.com/repos/{{repo}}/pulls/{{pr}}\"\n method: GET\n\n - id: review\n type: llm-prompt\n name: AI Code Review\n inputs:\n - from: nodes.fetch-diff.outputs.body\n to: diff\n config:\n promptTemplate: |\n Review this pull request for bugs and security issues:\n {{diff}}\n\n - id: route\n type: decision-routing\n name: Severity Check\n inputs:\n - from: nodes.review.outputs.response\n to: review\n config:\n prompt: \"Are there critical issues? {{review}}\"\n branches:\n block: \"Critical issues found\"\n approve: \"Clean code\"\n\nedges:\n - from: fetch-diff\n to: review\n - from: review\n to: route\n```\n\n---\n\n## Dark Factory\n\nThe **Dark Factory for Enterprise Software** is Stirrup's flagship template — a complete software development lifecycle in a single workflow.\n\n### How it works\n\n```\nRequirements Discovery → Solution Architecture →\n ┌─ Layer 1: Infrastructure (parallel) ─┐\n └─ Layer 2: Data Models (parallel) ────┘\n ↓\n Layer 3: Business Logic (sees Layer 2 types)\n ↓\n Layer 4: API Routes (sees Layers 2+3 interfaces)\n ↓\n Merge → Quality Review → Refine (conditional)\n ↓\n Completeness Sweep → Unit Tests + Integration Tests (parallel)\n ↓\n Security Audit → Production Review → Hardening (conditional)\n ↓\n Documentation → Assemble → Final Assessment → Git Push\n```\n\n**23 nodes, 32 edges.** Sequential-aware code generation means each layer sees the actual types and interfaces from prior layers — imports, method signatures, and DTOs are correct by construction. Dual quality gates route to refinement or hardening only when needed. Output is scaffolded to disk, pushed to a new GitHub repo.\n\n**Validated output quality:** Scored A grade (95 requirements, 92 code quality, 93 integration, 90 production readiness) on enterprise REST API generation across multiple test runs.\n\n### Variants\n\n| Template | Nodes | Approach |\n|----------|-------|----------|\n| `dark-factory-enterprise` | 23 | Production — sequential-aware + git delivery |\n| `dark-factory-brownfield` | 16 | Analyze existing repo → fix → PR → deploy |\n| `repo-momma` | 17 | ONE perfect improvement per run, self-review gate |\n| `dark-factory-v2` | 18 | Archive — parallel 4-layer |\n| `dark-factory-v3` | 19 | Archive — sequential-aware baseline |\n| `dark-factory-v4` | 23 | Archive — experimental test-driven feedback |\n\n---\n\n## Template Library\n\n35 ready-made workflow templates across 5 categories.\n\n### Software Development\n| Template | What it does |\n|----------|-------------|\n| **Dark Factory Enterprise** | Full-lifecycle software generation: requirements → architecture → multi-pass code gen → quality gates → tests → security → hardening → docs → git push |\n| **Dark Factory Brownfield** | Clone repo, analyze codebase, identify improvements, generate fixes, open PR, deploy preview to Launchmatic |\n| **Repo Momma** | Nurturing repo improvement — deep health check, measure gaps, pick ONE improvement, implement with care, self-review, PR |\n| **AI Code Gen & Validation** | Generate code from spec, review quality, produce deployment-ready output |\n| **PR Review Pipeline** | Fetch diff, AI review, severity routing, post results |\n| **PR Merge Deploy** | On PR merge, deploy to staging, run smoke tests, update PR with status |\n\n### DevOps & Infrastructure\n| Template | What it does |\n|----------|-------------|\n| **Deploy & Notify** | Deploy to Launchmatic, run browser smoke tests, post results to Slack |\n| **Release Pipeline** | GitHub release, deploy to production, screenshot result, announce in Slack |\n| **Self-Deploy to Launchmatic** | Package any Stirrup workflow as a standalone hosted service |\n| **Uptime Monitor** | Check URL on schedule, log metrics, alert in Slack on downtime |\n| **GitHub Issue Auto-Triage** | Classify issues, add labels, assign priority, notify team in Slack |\n\n### Content & Marketing\n| Template | What it does |\n|----------|-------------|\n| **Multi-Platform Launch Broadcast** | Fan out to LinkedIn, X, Facebook, TikTok, YouTube in parallel |\n| **Blog Multi-Channel Repurposer** | Fetch blog post, atomize into Twitter thread, LinkedIn, newsletter, YouTube script |\n| **AI Image Campaign** | Write 4 platform-tailored image prompts, generate via Replicate, pick winners, schedule posts |\n| **LinkedIn Daily Post** | Topic in, LinkedIn-tailored post out, published directly |\n| **LinkedIn Thought Leader** | RSS feed → AI commentary → publish to LinkedIn |\n| **SEO Content Brief** | SERP analysis → AI generates content brief with keyword strategy |\n| **Content Pipeline** | Research → outline → draft → quality review → revision → publish |\n\n### Analytics & Monitoring\n| Template | What it does |\n|----------|-------------|\n| **Weekly Repo Analytics** | PR/issue stats, top contributors, AI summary to Slack |\n| **Repo Health Broadcast** | GitHub stats → AI update → branded image → LinkedIn + Slack |\n| **LinkedIn Engagement Digest** | Pull post stats, analyze what's working, weekly digest to Slack |\n| **Competitor Changelog Watcher** | Fetch RSS, AI strategic summary, post to Slack |\n\n### Operations\n| Template | What it does |\n|----------|-------------|\n| **Customer Support Automation** | Classify tickets, route to team, auto-generate responses |\n| **Incident Triage & Response** | Parse alert, classify severity, run diagnostics, create response plan |\n| **Customer Feedback Router** | Classify sentiment, route negative to GitHub issues + Slack, positive to LinkedIn testimonial |\n| **Data ETL Pipeline** | Extract from API, AI-powered enrichment, load to destination |\n\nPlus smoke tests, meta-validators, and more. Browse all 35 in the UI or run `stirrup init`.\n\n---\n\n## Debug & Execution Monitor\n\nFull visibility into every execution. Inspect node-by-node results, see exact inputs and outputs, and diagnose failures with AI assistance.\n\n- **Real-time progress** — SSE-powered node status updates as the workflow runs\n- **Node inspector** — click any node to see config, inputs, outputs, and timing\n- **AI-powered debugging** — Claude reads the error, config, and inputs, then suggests specific fixes\n- **One-click apply** — review the AI's suggested edits with before/after diffs and apply them directly to the workflow\n- **Isolated retry** — re-run a single failed node with modified inputs without re-executing the entire workflow\n- **Resume after failure** — pick up from the failed node; completed nodes stay done, tokens are auto-re-injected\n- **Session restore** — reload the page and your last execution state is automatically rehydrated from SQLite\n\n---\n\n## Service Connections\n\nConnect once, use everywhere. Credentials are stored locally (`~/.stirrup/tokens.json`, 0600 permissions) and auto-injected into any workflow that declares a matching `service` param. Repo params use a smart GitHub picker — no URL typing.\n\n| Service | Auth method | What it powers |\n|---------|------------|----------------|\n| **GitHub** | OAuth device flow or `gh` CLI | PRs, issues, code search, repo picker, repo creation |\n| **Launchmatic** | `lm login` browser flow or manual paste | Deploy, databases, domains, browser tests |\n| **Anthropic** | API key (or `ANTHROPIC_API_KEY` env var) | AI nodes when model is `claude-*` or unspecified |\n| **Google Gemini** | API key (or `GEMINI_API_KEY` env var) | AI nodes when model is `gemini-*` (e.g., `gemini-2.5-flash`) |\n| **Slack** | Bot User OAuth Token (`xoxb-`) with guided setup | Messages, files, channels |\n| **LinkedIn** | OAuth token | Post to feed, org pages, engagement stats |\n| **Stripe** | Secret key or `stripe` CLI | Charges, customers, payments |\n| **Replicate** | API token | Image generation (Flux), any hosted model |\n| **Typefully** | API key | Schedule X/Twitter threads + LinkedIn posts |\n| **Buffer** | Access token | Schedule to Facebook, Instagram, Threads |\n| **AWS** | `aws configure` CLI | S3, Lambda, DynamoDB |\n| **Google Cloud** | `gcloud auth login` CLI | GCS, BigQuery, Cloud Run |\n\nEnvironment variables (e.g., `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GITHUB_TOKEN`) are detected automatically.\n\n---\n\n## CLI Reference\n\n```\nstirrup