Skip to content
Back to search

open-design

MarketplaceWorks with Claude CodeGitHub

OpenDesign — local-first design app exposed to coding agents over MCP. Install once with your agent's plugin command and projects/files/skills are reachable through stdio.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nexu-io/open-design with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nexu-io/open-design'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nexu-io-open-design/badge.svg)](/listings/nexu-io-open-design)

HTML

<a href="/listings/nexu-io-open-design"><img src="/api/listings/nexu-io-open-design/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.

These steps run a script from the network that findsafeskills does not scan.

🖥️ Download the desktop app (recommended — zero config)

The fastest way to use OpenDesign. No Node, no pnpm, no clone.

- **macOS** (Apple Silicon · Intel x64) → [**open-design.ai**](https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_download_macos) or [GitHub Releases](https://github.com/nexu-io/open-design/releases) - **Windows** (x64) → [**open-design.ai**](https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_download_windows) or [GitHub Releases](https://github.com/nexu-io/open-design/releases) - **Linux** → No prebuilt Linux artifact is currently published in the official releases. For now, [run OpenDesign from source](#-run-from-source); Linux release work is tracked in [#4368](https://github.com/nexu-io/open-design/issues/4368).

After install: the app auto-detects every coding-agent CLI on your `PATH`, loads 100+ functional skills, the separate rendering-template catalog, and 151 design systems, and lets you type a brief in the entry view.

🤖 Install into your coding agent (no UI)

You can use OpenDesign without ever opening the GUI — call it as a skill, plugin, or MCP server inside Claude Code, Codex, Cursor, Copilot, OpenClaw, Antigravity, Hermes, Kimi, and more.

If you installed the macOS desktop app via the DMG or Homebrew cask, your shell may still resolve `od` to Apple's built-in `/usr/bin/od` octal-dump utility. In that case, open **Settings → MCP server** in the desktop app and copy the client-specific snippet; it uses absolute paths and does not rely on the bare `od` command.

# One-line install into the agent you're using:
od mcp install <agent>
# <agent> = claude | codex | reasonix | raven | cursor | copilot | openclaw
#         | antigravity | pi | vibe | hermes | cline | kimi | kiro
#         | trae | opencode

# Hosted equivalent for curl-based setup:
curl -fsSL https://open-design.ai/install.sh | sh -s <agent>

`install.sh` is a thin shell wrapper around `od mcp install`; it exists so the hosted URL returns shell instead of the landing-page HTML fallback and fails fast if your shell resolves a non-Open-Design `od` binary.

> **macOS / WSL2 users:** `/usr/bin/od` is a system octal-dump command and can > shadow OpenDesign's `od` command. Desktop-app users should prefer the > **Settings → MCP server** snippet; WSL2 users should follow the > [`WSL2 setup guide`](docs/wsl-setup.md) first.

Then, inside the agent:

> Use open-design to generate a landing page with the Linear design system

In a filesystem-backed local CLI run, the agent composes the selected functional skill or design template with your `DESIGN.md`, writes the canonical project files, and OpenDesign previews those files. A BYOK/plain-API run without filesystem tools instead returns one complete `<artifact>` block.

🐳 Run with Docker

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
cp .env.example .env
echo "OD_API_TOKEN=$(openssl rand -hex 32)" >> .env
docker compose up -d
# open http://127.0.0.1:7456

If the browser asks for credentials, use `open-design` as the username and the `OD_API_TOKEN` value from `deploy/.env` as the password. This keeps Docker bridge traffic authenticated without requiring host networking. API clients can keep using `Authorization: Bearer <OD_API_TOKEN>`.

🚀 Deploy on Sealos

The Sealos App Store template runs the published OpenDesign Docker image with persistent workspace storage and Basic Auth on the public proxy. For custom public or shared Docker deployments, follow the reverse-proxy and `OPEN_DESIGN_ALLOWED_ORIGINS` guidance in [`deploy/README.md`](deploy/README.md#local-compose).

🧑‍💻 Run from source

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable && pnpm install
pnpm tools-dev run web

Open the URL printed by `tools-dev`; development ports are allocated dynamically unless you pass explicit port flags.

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 · 16 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schemas/marketplace.json",
  3. "name": "open-design",
  4. "owner": {
  5. "name": "nexu-io",
  6. "url": "https://github.com/nexu-io/open-design"
  7. },
  8. "description": "OpenDesign — local-first design app exposed to coding agents over MCP. Install once with your agent's plugin command and projects/files/skills are reachable through stdio.",
  9. "plugins": [
  10. {
  11. "name": "open-design",
  12. "source": "./plugins/open-design",
  13. "description": "OpenDesign MCP server (stdio). 139 skills + projects/files/preview tools, served by your local `od` daemon. Requires `od` on PATH (brew / npm / DMG)."
  14. }
  15. ]
  16. }
README.md · README · 747 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">OpenDesign: The 1st Collaborative AI Design Agent Workspace</h1>
  2. > ✨ **[Celebrating 100K GitHub stars with OpenDesign Go](https://open-design.ai/pricing/)** — Go credits are doubled: **$8 for your first month, with up to $120 in monthly credits for eligible Design Plan models**. Use them across 10+ models, including GPT-6 Luna, DeepSeek V4.1 Flash, GLM-5.3 Flash-X, and MiMo V2.6 Flash. All personal plans include API access for Codex, Claude Code, DSH, OpenCode, and more.
  3. <p align="center">
  4. <img src="docs/assets/readme-hero-design-agent.webp" alt="OpenDesign: The 1st Collaborative AI Design Agent Workspace" width="100%" />
  5. </p>
  6. <p align="center">
  7. <a href="https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_website">Website</a> ·
  8. <a href="https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_download">Download</a> ·
  9. <a href="https://open-design.ai/cloud/?utm_source=github&utm_medium=referral&utm_content=readme_cloud">OpenDesign Cloud</a> ·
  10. <a href="https://discord.gg/mHAjSMV6gz">Discord</a> ·
  11. <a href="https://x.com/OpenDesignHQ">Follow @OpenDesignHQ</a>
  12. </p>
  13. <p align="center">
  14. <a href="https://github.com/nexu-io/open-design/releases"><img alt="release" src="https://img.shields.io/github/v/release/nexu-io/open-design?style=flat&color=blueviolet&label=release&include_prereleases&display_name=tag" /></a>
  15. <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat" /></a>
  16. <a href="https://discord.gg/mHAjSMV6gz"><img alt="discord" src="https://img.shields.io/discord/1479002485040480266?style=flat&logo=discord&logoColor=white&label=discord&color=5865F2&cacheSeconds=3600" /></a>
  17. <a href="QUICKSTART.md"><img alt="quickstart" src="https://img.shields.io/badge/quickstart-3%20commands-green?style=flat" /></a>
  18. </p>
  19. <p align="center"><b>English</b> · <a href="docs/i18n/README.es.md">Español</a> · <a href="docs/i18n/README.pt-BR.md">Português</a> · <a href="docs/i18n/README.de.md">Deutsch</a> · <a href="docs/i18n/README.fr.md">Français</a> · <a href="docs/i18n/README.zh-CN.md">简体中文</a> · <a href="docs/i18n/README.zh-TW.md">繁體中文</a> · <a href="docs/i18n/README.ko.md">한국어</a> · <a href="docs/i18n/README.ja-JP.md">日本語</a> · <a href="docs/i18n/README.ar.md">العربية</a> · <a href="docs/i18n/README.ru.md">Русский</a> · <a href="docs/i18n/README.uk.md">Українська</a> · <a href="docs/i18n/README.tr.md">Türkçe</a> · <a href="docs/i18n/README.th.md">ภาษาไทย</a></p>
  20. ---
  21. ## What is OpenDesign
  22. OpenDesign is **the 1st collaborative AI design agent workspace**. Start with a brief, then use your coding agent or OpenDesign Cloud to create a prototype that follows your design system. Share it with your team for feedback, and let your agent refine it in the same project.
  23. That workflow is open and extensible. OpenDesign is licensed under Apache 2.0 and gives teams skills, design templates, design systems, and plugins they can inspect and adapt to their own process.
  24. ---
  25. ## Product tour
  26. ### Core pages
  27. <table>
  28. <tr>
  29. <td width="50%" valign="top">
  30. <a href="docs/screenshots/product-tour/home-workspace-2026-09-30-220844.png"><img src="docs/screenshots/product-tour/home-workspace-2026-09-30-220844.png" alt="OpenDesign Home page with the prototype composer and example prompts" width="500" /></a><br/>
  31. <sub><b>Home</b> — start with a brief or an example.</sub>
  32. </td>
  33. <td width="50%" valign="top">
  34. <a href="docs/screenshots/product-tour/all-projects-2026-09-30-220900.webp"><img src="docs/screenshots/product-tour/all-projects-2026-09-30-220900.webp" alt="OpenDesign All projects page showing recent design systems, media, and prototypes" width="500" /></a><br/>
  35. <sub><b>All projects</b> — revisit design systems, media, and prototypes.</sub>
  36. </td>
  37. </tr>
  38. <tr>
  39. <td width="50%" valign="top">
  40. <a href="docs/screenshots/product-tour/design-systems-stripe-2026-09-30-220910.png"><img src="docs/screenshots/product-tour/design-systems-stripe-2026-09-30-220910.png" alt="OpenDesign Design systems page showing the Stripe brand identity, logo, and typography" width="500" /></a><br/>
  41. <sub><b>Design Systems</b> — inspect brand assets and refine them with an agent.</sub>
  42. </td>
  43. <td width="50%" valign="top">
  44. <a href="docs/screenshots/product-tour/plugins-skills-2026-09-30-220917.png"><img src="docs/screenshots/product-tour/plugins-skills-2026-09-30-220917.png" alt="OpenDesign Plugins page showing official skills, categories, and search" width="500" /></a><br/>
  45. <sub><b>Plugins</b> — find skills and launch them with <code>Try it</code>.</sub>
  46. </td>
  47. </tr>
  48. </table>
  49. ### Studio — create and refine in one project
  50. <table>
  51. <tr>
  52. <td width="50%" valign="top">
  53. <img src="docs/screenshots/product-tour/studio-prototype-2026.webp" alt="Website prototype with live preview and agent conversation in OpenDesign Studio" /><br/>
  54. <sub><b>Prototype</b> — build and refine interactive web experiences with your agent and live preview.</sub>
  55. </td>
  56. <td width="50%" valign="top">
  57. <img src="docs/screenshots/product-tour/studio-slides-2026.png" alt="Swiss Grid presentation in OpenDesign Studio with slide thumbnails and speaker notes" /><br/>
  58. <sub><b>Slides</b> — create decks, review slides and speaker notes, and export when ready.</sub>
  59. </td>
  60. </tr>
  61. <tr>
  62. <td width="50%" valign="top">
  63. <img src="docs/screenshots/product-tour/studio-image-2026.webp" alt="Generated fashion portrait preview in OpenDesign Studio" /><br/>
  64. <sub><b>Image</b> — generate visual assets from the conversation, inspect the result, then download or open it.</sub>
  65. </td>
  66. <td width="50%" valign="top">
  67. <a href="docs/screenshots/product-tour/studio-hyperframes-2026.mp4"><img src="docs/screenshots/product-tour/studio-hyperframes-poster-2026.png" alt="OpenDesign HyperFrames editor showing the One brief, Every deliverable motion graphic" /></a><br/>
  68. <sub><b>HyperFrames</b> — create motion graphics with your agent and export to MP4. <a href="docs/screenshots/product-tour/studio-hyperframes-2026.mp4">Watch the video</a>.</sub>
  69. </td>
  70. </tr>
  71. </table>
  72. ---
  73. <!-- motion-template-library:start -->
  74. ## Product videos with OpenMotion
  75. Find a visual starting point for a product launch, feature demo, brand story, or milestone. Browse selected motion references and adaptation guides, copy a brief into your agent, and bring your own message, brand, and assets.
  76. Review and refine the generated project, then reuse it for your next release, campaign, or update.
  77. [Explore motion references and start creating →](docs/motion-templates/README.md)
  78. <!-- motion-template-library:end -->
  79. ---
  80. ## Platform Compatibility
  81. > OpenDesign connects to mainstream coding agents in two ways: **skills, CLI, and MCP** for agents that consume OD, plus **native runtime adapters** for agents that OD launches directly. DeepSeek Harness is a first-class native runtime through the official `dsh` CLI, with structured streaming, model discovery, cancellation, and session resume.
  82. | Coding agent / platform &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Status &nbsp;&nbsp; | Quick setup &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; |
  83. |---|:---:|---|
  84. | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✅ Supported | `od mcp install claude` |
  85. | [Claude Desktop](https://claude.ai/download) | ✅ Supported¹ | `od mcp install claude-desktop` |
  86. | [Codex CLI](https://github.com/openai/codex) | ✅ Supported | `od mcp install codex` |
  87. | [DeepSeek Reasonix](https://github.com/esengine/DeepSeek-Reasonix) | ✅ Supported | `od mcp install reasonix` |
  88. | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | ✅ Native runtime | `od agent setup deepseek-harness` |
  89. | [Raven](https://github.com/EverMind-AI/Raven) | ✅ Supported | `od mcp install raven` |
  90. | [Cursor](https://www.cursor.com/cli) | ✅ Supported | `od mcp install cursor` |
  91. | [VS Code + GitHub Copilot](https://github.com/features/copilot) | ✅ Supported | `od mcp install copilot` |
  92. | [GitHub Copilot CLI](https://github.com/features/copilot/cli) | ✅ Supported | `od mcp install copilot` |
  93. | [OpenCode](https://opencode.ai/) | ✅ Supported | `od mcp install opencode` |
  94. | [OpenClaw](https://github.com/openclaw/openclaw) | ✅ Supported | `od mcp install openclaw` |
  95. | [Antigravity](https://antigravity.google) | ✅ Supported | `od mcp install antigravity` |
  96. | [Cline](https://github.com/cline/cline) | ✅ Supported | `od mcp install cline` |
  97. | [Trae](https://www.trae.ai/) | ✅ Supported | `od mcp install trae` |
  98. | [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | ✅ Supported | `od mcp install kimi` |
  99. | [Kiro](https://kiro.dev) | ✅ Supported | `od mcp install kiro` |
  100. | [Pi Agent](https://github.com/badlogic/pi-mono) | ✅ Supported | `od mcp install pi` |
  101. | [Mistral Vibe CLI](https://github.com/mistralai/mistral-vibe) | ✅ Supported | `od mcp install vibe` |
  102. | [Hermes Agent](https://github.com/nousresearch/hermes-agent) | ✅ Supported | `od mcp install hermes` |
  103. For DeepSeek Harness, install the official `dsh` CLI first, then select it in OpenDesign or run `od agent setup deepseek-harness` to install/repair OD's connection component. For MCP integrations: `od mcp install <agent> --print` for a dry-run preview · `--uninstall` to remove · full list with `od mcp install --help`.
  104. ¹ Automatic MCP configuration for Claude Desktop is currently supported on macOS and Windows only.
  105. <p align="center">
  106. <img src="https://repo-assets.open-design.ai/resources/images/coding-agents.png" alt="The 26 coding-agent CLIs OpenDesign supports — DeepSeek Harness · Claude Code · Codex · OpenCode · Hermes · Antigravity · Vela · Grok Build · Kimi · Cursor Agent · Qwen · Qoder · GitHub Copilot · Pi · Kiro · Kilo · Mistral Vibe · DeepSeek · Reasonix · Aider · Amp · CodeBuddy · Mimo · AtomCode · Devin · Trae" width="100%" />
  107. </p>
  108. **No CLI installed?** The BYOK proxy at `POST /api/proxy/{anthropic,openai,azure,google,ollama,senseaudio}/stream` gives you the same loop (no process spawn) — paste `baseUrl` + `apiKey` + `model`, with presets for OpenAI, Atlas Cloud, Anthropic, Azure OpenAI, Google Gemini, Ollama, LM Studio, vLLM, or any OpenAI-compatible endpoint. Atlas Cloud uses `https://api.atlascloud.ai/v1` with your own key and OpenAI-compatible model ids such as `qwen/qwen3.5-flash`. Per-target SSRF protection blocks internal IPs / link-local / CGNAT at the daemon edge.
  109. Runtime definitions live in [`apps/daemon/src/runtimes/defs/`](apps/daemon/src/runtimes/defs/), with registration and shared stream handling under [`apps/daemon/src/runtimes/`](apps/daemon/src/runtimes/). See [`docs/agent-adapters.md`](docs/agent-adapters.md) for the adapter contract.
  110. ---
  111. ## Demo
  112. Four core product categories, all rendered by a coding agent running on your laptop. Click a thumbnail to see the real example.
  113. ### 1 · Prototypes — web · desktop · mobile
  114. The default output surface. Single-page HTML artifacts that read your `DESIGN.md` and render in a sandboxed iframe.
  115. <table>
  116. <tr>
  117. <td width="50%" valign="top">
  118. <img src="docs/screenshots/skills/dating-web.png" alt="Web prototype dating-web" /><br/>
  119. <sub><b>Web prototype</b> — an editorial dashboard with scrollbars, KPIs, and charts. Rendered straight from <code>design-templates/dating-web/</code>.</sub>
  120. </td>
  121. <td width="50%" valign="top">
  122. <img src="docs/screenshots/skills/gamified-app.png" alt="Gamified app" /><br/>
  123. <sub><b>Mobile app prototype</b> — a three-screen gamified flow with XP ribbons and quest detail. Hand off straight to Cursor / Codex / Claude Code to turn into React/Next/Vue.</sub>
  124. </td>
  125. </tr>
  126. </table>
  127. ### 2 · Live artifacts & dashboards
  128. Live dashboards, decision rooms, KPI walls — single-page artifacts that pull data through a tweaks panel and stay editable in place.
  129. <table>
  130. <tr>
  131. <td width="50%" valign="top">
  132. <img src="docs/screenshots/skills/live-dashboard.png" alt="Live dashboard" /><br/>
  133. <sub><b>Live dashboard</b> — an editable KPI wall whose tweaks panel surfaces the parameters worth nudging. The agent emits a manifest, and the iframe re-renders without a reload.</sub>
  134. </td>
  135. <td width="50%" valign="top">
  136. <img src="docs/screenshots/skills/research-decision-room.png" alt="Decision room" /><br/>
  137. <sub><b>Decision room</b> — a multi-source briefing artifact for product / research / ops meetings.</sub>
  138. </td>
  139. </tr>
  140. <tr>
  141. <td width="50%" valign="top">
  142. <img src="docs/screenshots/skills/github-dashboard.png" alt="GitHub dashboard" /><br/>
  143. <sub><b>GitHub-style dashboard</b> — repo metrics presented as a live artifact.</sub>
  144. </td>
  145. <td width="50%" valign="top">
  146. <img src="docs/screenshots/skills/flowai-live-dashboard-template.png" alt="Flow live dashboard" /><br/>
  147. <sub><b>Flow live-dashboard template</b> — a domain-specific KPI template, branded through the active <code>DESIGN.md</code>.</sub>
  148. </td>
  149. </tr>
  150. </table>
  151. ### 3 · Decks — magazine decks, weekly updates, pitches
  152. <table>
  153. <tr>
  154. <td width="50%" valign="top">
  155. <img src="docs/screenshots/07-magazine-deck.png" alt="Magazine deck (guizang-ppt)" /><br/>
  156. <sub><b>Deck mode (guizang-ppt)</b> — magazine layouts, WebGL hero, P0/P1/P2 checklists. Bundled verbatim from <a href="https://github.com/op7418/guizang-ppt-skill"><code>op7418/guizang-ppt-skill</code></a> with its original license preserved.</sub>
  157. </td>
  158. <td width="50%" valign="top">
  159. <img src="docs/screenshots/skills/deck-swiss-international.png" alt="Swiss deck" /><br/>
  160. <sub><b>Swiss International-style deck</b> — grid-anchored, monochrome accents. One of <b>15 deck templates</b> and <b>36 themes</b> under <code>design-templates/html-ppt-*/</code>.</sub>
  161. </td>
  162. </tr>
  163. </table>
  164. Every deck exports to **HTML** (single file, inlined assets), **PDF** (browser print, deck-aware), **PPTX** (agent-driven skill), **ZIP** (archive), or **Markdown**.
  165. ### 4 · Images — `gpt-image-2`, ImageRouter, custom API
  166. <table>
  167. <tr>
  168. <td width="20%" valign="top"><img src="https://cms-assets.youmind.com/media/1776662673014_nf0taw_HGRMNDybsAAGG88.jpg" alt="Illustrated city food map" /><br/><sub><b>Illustrated city food map</b><br/>Hand-drawn editorial travel poster</sub></td>
  169. <td width="20%" valign="top"><img src="https://cms-assets.youmind.com/media/1777453149026_gd2k50_HHCSvymboAAVscc.jpg" alt="Cinematic elevator scene" /><br/><sub><b>Cinematic elevator scene</b><br/>Single-frame editorial still</sub></td>
  170. <td width="20%" valign="top"><img src="https://cms-assets.youmind.com/media/1777453164993_mt5b69_HHDoWfeaUAEA6Vt.jpg" alt="Cyberpunk anime portrait" /><br/><sub><b>Cyberpunk portrait</b><br/>Profile avatar — neon face text</sub></td>
  171. <td width="20%" valign="top"><img src="https://cms-assets.youmind.com/media/1776661968404_8a5flm_HGQc_KOaMAA2vt0.jpg" alt="3D stone staircase evolution" /><br/><sub><b>3D stone staircase</b><br/>Hewn-stone infographic</sub></td>
  172. <td width="20%" valign="top"><img src="https://cms-assets.youmind.com/media/1777453184257_vb9hvl_HG9tAkOa4AAuRrn.jpg" alt="Glamorous portrait" /><br/><sub><b>Glamorous portrait</b><br/>Editorial studio shot</sub></td>
  173. </tr>
  174. </table>
  175. **93 ready-to-replicate prompts** live in [`prompt-templates/`](prompt-templates/) — preview thumbnails, full prompt body, target model, aspect ratio, and source attribution. One click drops a brief into the composer.
  176. ### 5 · Video & HyperFrames — agent-native motion graphics
  177. **[HyperFrames][hyperframes]** is HeyGen's open-source, agent-native video framework, integrated as a first-class citizen in OpenDesign. The agent writes HTML + CSS + GSAP, and HyperFrames renders it to a deterministic MP4 via headless Chrome + FFmpeg. Pair it with **Seedance 2.0** for cinematic t2v / i2v, **Veo 3 / Sora 2 / Kling 2** for routed model variants, and **Suno v5 / Lyria 2** for the audio layer.
  178. <table>
  179. <tr>
  180. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-saas-product-promo-30s.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/app-showcase.png" alt="SaaS promo" /></a><br/><sub><b>30s SaaS product promo</b> · 16:9 · UI 3D reveals</sub></td>
  181. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-tiktok-karaoke-talking-head.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/tiktok-follow.png" alt="TikTok karaoke" /></a><br/><sub><b>TikTok karaoke talking-head</b> · 9:16 · TTS + word-synced captions</sub></td>
  182. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-brand-sizzle-reel.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/logo-outro.png" alt="Brand sizzle reel" /></a><br/><sub><b>30s brand sizzle reel</b> · 16:9 · audio-reactive kinetic type</sub></td>
  183. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-data-bar-chart-race.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/data-chart.png" alt="Bar chart race" /></a><br/><sub><b>Bar chart race</b> · 16:9 · NYT-style data infographic</sub></td>
  184. </tr>
  185. <tr>
  186. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-flight-map-route.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/nyc-paris-flight.png" alt="Flight map" /></a><br/><sub><b>Flight map</b> · 16:9 · Apple-style route reveal</sub></td>
  187. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-logo-outro-cinematic.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/logo-outro.png" alt="Logo outro" /></a><br/><sub><b>4s cinematic logo outro</b> · 16:9 · piece-by-piece assembly + bloom</sub></td>
  188. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-money-counter-hype.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/apple-money-count.png" alt="Money counter" /></a><br/><sub><b>$0 → $10K money counter</b> · 9:16 · Apple-style hype</sub></td>
  189. <td width="25%" valign="top"><a href="prompt-templates/video/hyperframes-website-to-video-promo.json"><img src="https://static.heygen.ai/hyperframes-oss/docs/images/catalog/blocks/instagram-follow.png" alt="Website to video" /></a><br/><sub><b>Website-to-video</b> · 16:9 · captures the site at 3 viewports</sub></td>
  190. </tr>
  191. </table>
  192. 11 HyperFrames templates + 39 Seedance prompts ship with the repo. Catalog thumbnails © HeyGen; the framework is Apache-2.0. The OD-specific render workflow (composition cache, sandbox-exec workaround, MP4-as-chip) is detailed in [`design-templates/hyperframes/`](design-templates/hyperframes/).
  193. [hyperframes]: https://github.com/heygen-com/hyperframes
  194. ---
  195. ## Why OpenDesign
  196. - 🤖 **Agent-native, model-agnostic.** We don't ship an agent. The `claude` / `codex` / `cursor-agent` / `copilot` / `hermes` / `kimi` already on your `PATH` are the design engine. Swap with one click.
  197. - 🧠 **Brand-grade by default.** Every render reads the active package's `DESIGN.md` as the core brand contract. 151 design-system packages ship with the repo; legacy packages may be `DESIGN.md`-only, while newer packages can add `manifest.json`, `tokens.css`, components, assets, and provenance. Drop a folder in, the picker finds it.
  198. - 🖥️ **Local-first, BYOK at every layer.** Native desktop apps for macOS (Apple Silicon + Intel) and Windows (x64). Linux desktop users can currently run OpenDesign [from source](#-run-from-source); the latest official release does not include a prebuilt Linux artifact. Product analytics and session replay are consent-gated; scrubbed safety and reliability telemetry is always on. Before describing daemon data paths, contributors and operators MUST read `AGENTS.md` → **Daemon data directory contract**. This README MUST NOT restate it.
  199. - 🌍 **Composable on four planes.** **Plugins** carry runnable workflows · functional **skills** carry agent behavior · **design templates** carry rendering blueprints · **design systems** carry the brand. All four use portable, versionable directories that anyone can author and publish.
  200. - 🔁 **Refresh an existing codebase.** Hand a `git` repo + `DESIGN.md` to the agent and it refactors your real components to the brand spec.
  201. - 🔒 **Privacy by conviction.** Projects can run locally or in your own deployment. Cloud model and OpenDesign Cloud requests are sent to the corresponding services. The BYOK proxy includes SSRF safeguards.
  202. ---
  203. ## Quick start
  204. ### 🖥️ Download the desktop app (recommended — zero config)
  205. The fastest way to use OpenDesign. No Node, no pnpm, no clone.
  206. - **macOS** (Apple Silicon · Intel x64) → [**open-design.ai**](https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_download_macos) or [GitHub Releases](https://github.com/nexu-io/open-design/releases)
  207. - **Windows** (x64) → [**open-design.ai**](https://open-design.ai/?utm_source=github&utm_medium=referral&utm_content=readme_download_windows) or [GitHub Releases](https://github.com/nexu-io/open-design/releases)
  208. - **Linux** → No prebuilt Linux artifact is currently published in the official releases. For now, [run OpenDesign from source](#-run-from-source); Linux release work is tracked in [#4368](https://github.com/nexu-io/open-design/issues/4368).
  209. After install: the app auto-detects every coding-agent CLI on your `PATH`, loads 100+ functional skills, the separate rendering-template catalog, and 151 design systems, and lets you type a brief in the entry view.
  210. ### 🤖 Install into your coding agent (no UI)
  211. You can use OpenDesign without ever opening the GUI — call it as a skill, plugin, or MCP server inside Claude Code, Codex, Cursor, Copilot, OpenClaw, Antigravity, Hermes, Kimi, and more.
  212. If you installed the macOS desktop app via the DMG or Homebrew cask, your shell
  213. may still resolve `od` to Apple's built-in `/usr/bin/od` octal-dump utility. In
  214. that case, open **Settings → MCP server** in the desktop app and copy the
  215. client-specific snippet; it uses absolute paths and does not rely on the bare
  216. `od` command.
  217. ```bash
  218. # One-line install into the agent you're using:
  219. od mcp install <agent>
  220. # <agent> = claude | codex | reasonix | raven | cursor | copilot | openclaw
  221. # | antigravity | pi | vibe | hermes | cline | kimi | kiro
  222. # | trae | opencode
  223. # Hosted equivalent for curl-based setup:
  224. curl -fsSL https://open-design.ai/install.sh | sh -s <agent>
  225. ```
  226. `install.sh` is a thin shell wrapper around `od mcp install`; it exists so the
  227. hosted URL returns shell instead of the landing-page HTML fallback and fails
  228. fast if your shell resolves a non-Open-Design `od` binary.
  229. > **macOS / WSL2 users:** `/usr/bin/od` is a system octal-dump command and can
  230. > shadow OpenDesign's `od` command. Desktop-app users should prefer the
  231. > **Settings → MCP server** snippet; WSL2 users should follow the
  232. > [`WSL2 setup guide`](docs/wsl-setup.md) first.
  233. Then, inside the agent:
  234. ```
  235. > Use open-design to generate a landing page with the Linear design system
  236. ```
  237. In a filesystem-backed local CLI run, the agent composes the selected functional skill or design template with your `DESIGN.md`, writes the canonical project files, and OpenDesign previews those files. A BYOK/plain-API run without filesystem tools instead returns one complete `<artifact>` block.
  238. ### 🐳 Run with Docker
  239. ```bash
  240. git clone https://github.com/nexu-io/open-design.git
  241. cd open-design/deploy
  242. cp .env.example .env
  243. echo "OD_API_TOKEN=$(openssl rand -hex 32)" >> .env
  244. docker compose up -d
  245. # open http://127.0.0.1:7456
  246. ```
  247. If the browser asks for credentials, use `open-design` as the username and the
  248. `OD_API_TOKEN` value from `deploy/.env` as the password. This keeps Docker bridge
  249. traffic authenticated without requiring host networking. API clients can keep
  250. using `Authorization: Bearer <OD_API_TOKEN>`.
  251. ### 🚀 Deploy on Sealos
  252. [![Deploy on Sealos](https://sealos.io/Deploy-on-Sealos.svg)](https://sealos.io/products/app-store/open-design/)
  253. The Sealos App Store template runs the published OpenDesign Docker image with persistent workspace storage and Basic Auth on the public proxy. For custom public or shared Docker deployments, follow the reverse-proxy and `OPEN_DESIGN_ALLOWED_ORIGINS` guidance in [`deploy/README.md`](deploy/README.md#local-compose).
  254. ### 🧑‍💻 Run from source
  255. ```bash
  256. git clone https://github.com/nexu-io/open-design.git
  257. cd open-design
  258. corepack enable && pnpm install
  259. pnpm tools-dev run web
  260. ```
  261. Open the URL printed by `tools-dev`; development ports are allocated dynamically unless you pass explicit port flags.
  262. Node `~24`, pnpm `10.33.x`. WSL2 users, see [`docs/wsl-setup.md`](docs/wsl-setup.md); native Windows users, see [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md). Full quickstart, env vars, and packaged build flow → [`QUICKSTART.md`](QUICKSTART.md).
  263. ### A full workflow — from brief to artifact
  264. `brief → plugin → direction → design system → artifact → handoff → memory`
  265. 1. **A PM submits a brief.** The plugin picker offers landing page · pitch deck · dashboard · social post · PM spec · OKR scorecard…
  266. 2. **A designer (or the agent) locks the direction.** No brand? Pick from 5 curated directions. Have a brand? Drop a screenshot / URL → the agent connects GitHub and codifies a reusable `DESIGN.md`.
  267. 3. **The agent creates the first deliverable.** Plugin + functional skill or design template + `DESIGN.md` are bound. Filesystem-backed CLI runs write canonical project files and the preview follows them; BYOK/plain-API runs without file tools return one complete `<artifact>` block.
  268. 4. **Hand off to engineering.** The artifact is real HTML/CSS — drop it into Cursor, Codex, or Claude Code to keep building as code. Or export PPTX / PDF / MP4 straight to marketing.
  269. 5. **OpenDesign gets smarter as you use it.** Your screenshots, fonts, palettes, and confirmed artifacts accumulate as defaults for the next session. Less rework, less drift.
  270. ---
  271. ## Use OpenDesign from your coding agent
  272. OpenDesign ships a **stdio MCP server** and per-agent **install scripts**. Any MCP-compatible agent in another repo can read files from your local OpenDesign projects directly — tokens CSS, JSX components, entry HTML — as a structured API queryable by name. The agent always sees the live file, not a stale export.
  273. ```bash
  274. # One-line install (16+ CLIs supported):
  275. od mcp install <agent>
  276. # Then the agent can:
  277. od project list --json
  278. od files list <project-id> --json
  279. od files read <project-id> <relative-path>
  280. od plugin list --json
  281. od skills list --json
  282. ```
  283. **Why MCP?** Exporting and re-attaching a zip every iteration breaks flow. MCP exposes the design source directly — the agent always sees the live file.
  284. **For an agent starting from scratch,** the installer places `~/.config/<agent>/open-design.json` (or the platform equivalent) plus a copy-paste MCP snippet. Cursor gets a one-click deeplink; Claude Code gets a `claude mcp add-json` one-liner; every other agent gets JSON in the schema its config expects. On macOS desktop installs, prefer that Settings snippet over typing bare `od mcp install <agent>` in Terminal, because `/usr/bin/od` may win on PATH. Full per-agent flow → **Settings → MCP server** in the desktop app, or [`docs/agent-adapters.md`](docs/agent-adapters.md).
  285. **Security model.** Read-only by default, the daemon binds to `127.0.0.1`, and SSRF is blocked at the proxy edge. LAN exposure requires an explicit `OD_BIND_HOST` plus `OD_ALLOWED_ORIGINS`. Connector credentials and live-artifact preview routes stay loopback-only regardless.
  286. **Internally-hosted model endpoints.** To prevent SSRF, the daemon blocks provider base URLs that resolve to private/internal address ranges (RFC1918, link-local, CGNAT, and cloud-metadata IPs) by default, surfacing `Internal IPs blocked`. If you run an internally-hosted gateway (e.g. LiteLLM or Ollama on a VPN-only `10.x`/`192.168.x` address), opt that host out with `OD_ALLOWED_INTERNAL_HOSTS=<host1>,<host2>,...` — a comma- or whitespace-separated list of bare hostnames or IPs (`10.0.0.5`, `litellm.internal.corp`; a `host:port` or full URL is accepted and reduced to its hostname; IPv6 must be bracketed, e.g. `[fd00::1]`). The allowlist is strict opt-in (empty by default), exact-host (no subdomain/substring matching), and applies **only** to provider endpoints you configure (connection test, model discovery, BYOK chat). It deliberately does **not** relax the guard on download URLs returned inside upstream responses, which stay blocked. A malformed entry — or CIDR notation, which is not supported — is dropped with a warning rather than silently trusted, so a typo never quietly widens (or fails to widen) the guard. Allowlisting a hostname trusts whatever it resolves to (like `OD_ALLOWED_ORIGINS`); allowlist the resolved IP instead if you want the DNS-resolved address re-checked.
  287. ---
  288. ## Skills and design templates
  289. **100+ functional skills ship in [`skills/`](skills/)**. Each follows the Agent Skills [`SKILL.md`][skill] convention and supplies reusable agent behavior, references, or utilities. Renderable starters live separately in [`design-templates/`](design-templates/); they may also use `SKILL.md`, but they populate the design-template catalog rather than the functional-skill registry.
  290. Two **modes** anchor the design-template catalog: `prototype` (web/mobile/desktop single-page artifacts) and `deck` (horizontal-swipe presentations). Other templates cover `image`, `video`, `audio`, and utility surfaces. The **`scenario`** field groups templates by audience: `design` · `marketing` · `operation` · `engineering` · `product` · `finance` · `hr` · `sale` · `personal`.
  291. | Design template | Mode | Scenario | What it produces |
  292. |---|---|---|---|
  293. | [`web-prototype`](design-templates/web-prototype/) | prototype | design | Default landing page / hero |
  294. | [`saas-landing`](design-templates/saas-landing/) | prototype | marketing | Hero / features / pricing / CTA |
  295. | [`dashboard`](design-templates/dashboard/) | prototype | operation | Admin / analytics (with sidebar) |
  296. | [`mobile-app`](design-templates/mobile-app/) | prototype | design | iPhone 15 Pro / Pixel framed app |
  297. | [`mobile-onboarding`](design-templates/mobile-onboarding/) | prototype | design | Splash · value-prop · sign-in flow |
  298. | [`social-carousel`](design-templates/social-carousel/) | prototype | marketing | 3-card 1080×1080 carousel |
  299. | [`email-marketing`](design-templates/email-marketing/) | prototype | marketing | Table-fallback-safe brand email |
  300. | [`magazine-poster`](design-templates/magazine-poster/) | prototype | marketing | Single-page magazine layout |
  301. | [`motion-frames`](design-templates/motion-frames/) | prototype | marketing | Looping CSS motion hero |
  302. | [`sprite-animation`](design-templates/sprite-animation/) | prototype | marketing | 8-bit pixel animated explainer |
  303. | [`pm-spec`](design-templates/pm-spec/) | prototype | product | PM spec doc (with TOC + decision log) |
  304. | [`team-okrs`](design-templates/team-okrs/) | prototype | product | OKR scorecard |
  305. | [`eng-runbook`](design-templates/eng-runbook/) | prototype | engineering | Incident runbook |
  306. | [`finance-report`](design-templates/finance-report/) | prototype | finance | Exec finance summary |
  307. | [`hr-onboarding`](design-templates/hr-onboarding/) | prototype | hr | Role onboarding plan |
  308. | [`guizang-ppt`](design-templates/guizang-ppt/) | deck | marketing | Magazine-style web PPT (deck default) |
  309. | [`html-ppt-*`](design-templates/) | deck | marketing | 15 deck templates × 36 themes (master template in [`design-templates/html-ppt/`](design-templates/html-ppt/)) |
  310. | [`hyperframes`](design-templates/hyperframes/) | video | marketing | HTML → MP4 motion graphics (HeyGen OSS framework) |
  311. | [`critique`](design-templates/critique/) | utility | design | Five-dimensional self-critique scoresheet |
  312. | [`tweaks`](design-templates/tweaks/) | utility | design | AI-emitted tweaks-panel manifest |
  313. Full protocol and directory split → [`docs/skills-protocol.md`](docs/skills-protocol.md). Registry endpoints: `GET /api/skills` for functional skills and `GET /api/design-templates` for rendering templates.
  314. ---
  315. ## Design Systems
  316. **151 brand-grade design-system packages centered on `DESIGN.md`** ship with the repo. Legacy packages may contain only that Markdown contract; newer packages can also carry `manifest.json`, compiled `tokens.css`, component fixtures, assets, and provenance evidence. The catalog mixes upstream-derived systems with project-owned additions; [`design-systems/README.md`](design-systems/README.md) records the package shape and provenance. Switch a system → the next render uses the new tokens.
  317. <details>
  318. <summary><b>Full catalog (click to expand)</b></summary>
  319. **AI & LLM** — `claude` · `cohere` · `mistral-ai` · `minimax` · `together-ai` · `replicate` · `runwayml` · `elevenlabs` · `ollama` · `x-ai`
  320. **Developer Tools** — `cursor` · `vercel` · `linear-app` · `expo` · `clickhouse` · `mongodb` · `supabase` · `hashicorp` · `posthog` · `sentry` · `warp` · `sanity` · `mintlify` · `composio` · `opencode-ai` · `voltagent`
  321. **Productivity** — `notion` · `miro` · `airtable` · `superhuman` · `intercom` · `zapier` · `cal` · `clay` · `raycast`
  322. **Fintech** — `stripe` · `coinbase` · `binance` · `kraken` · `mastercard` · `revolut` · `wise`
  323. **E-commerce** — `shopify` · `airbnb` · `uber` · `nike` · `starbucks` · `pinterest`
  324. **Media** — `spotify` · `playstation` · `wired` · `theverge` · `meta`
  325. **Automotive** — `tesla` · `bmw` · `ferrari` · `lamborghini` · `bugatti` · `renault`
  326. **Other** — `apple` · `ibm` · `nvidia` · `vodafone` · `resend` · `spacex`
  327. **Starters** — `default` (Neutral Modern) · `warm-editorial`
  328. </details>
  329. Re-import the library via [`scripts/sync-design-systems.ts`](scripts/sync-design-systems.ts). Add your own brand → drop a `DESIGN.md` into `design-systems/<brand>/`. Full guide → [`design-systems/README.md`](design-systems/README.md).
  330. [acd2]: https://github.com/VoltAgent/awesome-design-md
  331. ---
  332. ## Plugins
  333. **277 official plugins plus 183 remixable reference examples** live in [`plugins/_official/`](plugins/_official/). Each entry is a portable plugin directory anchored by `open-design.json` plus the payload required by its type: for example `SKILL.md` for agent workflows, `template.json` for media templates, or `DESIGN.md` for design-system entries. Jump straight to a category:
  334. | Category | Count | Contents |
  335. |---|---|---|
  336. | [`scenarios/`](plugins/_official/scenarios/) | 13 | Complete design scenarios — [`od-default`](plugins/_official/scenarios/od-default/), [`od-design-refine`](plugins/_official/scenarios/od-design-refine/), [`od-figma-migration`](plugins/_official/scenarios/od-figma-migration/), [`od-code-migration`](plugins/_official/scenarios/od-code-migration/), [`od-react-export`](plugins/_official/scenarios/od-react-export/), [`od-nextjs-export`](plugins/_official/scenarios/od-nextjs-export/), [`od-vue-export`](plugins/_official/scenarios/od-vue-export/), [`od-media-generation`](plugins/_official/scenarios/od-media-generation/), [`od-new-generation`](plugins/_official/scenarios/od-new-generation/), [`od-tune-collab`](plugins/_official/scenarios/od-tune-collab/), [`od-plugin-authoring`](plugins/_official/scenarios/od-plugin-authoring/), [`od-share-to-community`](plugins/_official/scenarios/od-share-to-community/), [`od-web-effect-extractor`](plugins/_official/scenarios/od-web-effect-extractor/) |
  337. | [`image-templates/`](plugins/_official/image-templates/) | 45 | One-shot image prompts — editorial, cinematic, product, portrait |
  338. | [`video-templates/`](plugins/_official/video-templates/) | 63 | HyperFrames / Seedance / Veo motion templates |
  339. | [`design-systems/`](plugins/_official/design-systems/) | 143 | Brand `DESIGN.md` wrapped as plugins |
  340. | [`atoms/`](plugins/_official/atoms/) | 13 | Reusable UI fragments (buttons, heroes, KPI cards) |
  341. | [`examples/`](plugins/_official/examples/) | 183 | Remixable reference outputs |
  342. Also [`plugins/community/`](plugins/community/) for community plugins and [`plugins/registry/`](plugins/registry/) for the publishing flow.
  343. ### What plugins can do
  344. - 🤖 **Run in any coding agent** — [Claude Code](docs/agent-adapters.md), Codex, Cursor, Copilot, [OpenClaw](https://github.com/openclaw/openclaw), [Antigravity](https://antigravity.google), Hermes, Kimi… through the same skill protocol the agent already knows.
  345. - 🔁 **Migrate Figma / Pencil workflows** → React, Next.js, or Vue source. See [`od-figma-migration`](plugins/_official/scenarios/od-figma-migration/).
  346. - 🛠️ **Refresh an existing codebase to a brand spec** — point a plugin at a `git` repo + `DESIGN.md`, get a PR. See [`od-code-migration`](plugins/_official/scenarios/od-code-migration/).
  347. - 💾 **Persist custom workflows** — your team's reusable templates sit next to the shipped ones.
  348. ### Using plugins
  349. Plugins are at full parity across the **web UI** and the **`od` CLI** — same `/api/plugins` endpoints, pick whichever fits.
  350. **In the desktop / web app:** open the **Plugin** page to browse the marketplace and click **Install**; inside a project's Studio, plugins appear as composer chips you click to apply (with the inputs they declare).
  351. **On the command line** (runs without a UI — this is the path external agents use):
  352. ```bash
  353. od plugin list # list installed plugins (--task-kind / --mode / --tag filters)
  354. od plugin search "landing page" # search by keyword
  355. od plugin info od-default # inspect a plugin's metadata, inputs, capabilities
  356. od plugin install od-default # install from a registry; also accepts ./local-folder or an https://… link
  357. od plugin apply od-default --input brief="a one-page pitch for our seed round"
  358. od plugin upgrade od-default # upgrade
  359. od plugin uninstall od-default # uninstall
  360. ```
  361. Every command supports `--json`, so you can pipe it through `jq` / `xargs` into automation.
  362. ### Building a plugin
  363. An OpenDesign plugin requires `open-design.json` plus the payload required by its type. A workflow skill or scenario also includes `SKILL.md`; manifest-only template and design-system entries use their own payloads instead:
  364. ```
  365. my-plugin/
  366. ├── open-design.json ← required: marketplace metadata + inputs + pipeline + capabilities
  367. ├── SKILL.md ← required for agent-skill/scenario entries; omitted for other plugin types
  368. ├── README.md ← optional: usage, install, registry links
  369. ├── preview/ ← optional: index.html / poster.png (strongly recommended for visual plugins)
  370. └── examples/ ← optional: concrete use cases
  371. ```
  372. Core `open-design.json` fields: `specVersion` (currently `1.0.0`), `name` (stable ID), `version` (semver), optional `compat.agentSkills[].path` (points at `./SKILL.md` when the entry exposes an Agent Skill), `od.kind` (`skill` / `scenario` / `atom` / `bundle`), `od.taskKind` (`new-generation` / `figma-migration` / `code-migration` / `tune-collab`), `od.mode` (the output surface, e.g. `prototype` / `deck` / `live-artifact` / `image` / `video` / `hyperframes` / `audio` / `design-system` / `scenario`), `od.capabilities[]` (**declare the minimum** — a restricted install grants only `prompt:inject` by default), `od.inputs[]` (apply-time parameters).
  373. Scaffold + validate locally:
  374. ```bash
  375. od plugin scaffold --id my-plugin --title "My Plugin" # generate the skeleton
  376. od plugin validate ./my-plugin # check manifest / file layout
  377. pnpm guard && pnpm --filter @open-design/plugin-runtime typecheck
  378. ```
  379. Full field set and runtime contract → [`plugins/spec/SPEC.md`](plugins/spec/SPEC.md); developing a plugin with a coding agent → [`plugins/spec/AGENT-DEVELOPMENT.md`](plugins/spec/AGENT-DEVELOPMENT.md); copy-paste minimal templates → [`plugins/spec/examples/`](plugins/spec/examples/).
  380. ### Contributing a plugin
  381. 1. Drop the plugin folder into [`plugins/community/`](plugins/community/) (third-party plugins), or — to ship it bundled with OpenDesign — into the matching tier of [`plugins/_official/`](plugins/_official/).
  382. 2. Pass validation: `od plugin validate`, `pnpm guard`, `pnpm --filter @open-design/plugin-runtime typecheck`.
  383. 3. Fill the PR using the template in [`plugins/spec/CONTRIBUTING.md`](plugins/spec/CONTRIBUTING.md) (ID, version, lane, mode, capabilities, trigger examples; attach a screenshot / preview for visual plugins).
  384. 4. To publish to an external registry (skills.sh / ClawHub / standalone GitHub) → [`plugins/spec/PUBLISHING-REGISTRIES.md`](plugins/spec/PUBLISHING-REGISTRIES.md).
  385. Plugin registry endpoint: `GET /api/plugins`. Directory overview → [`plugins/README.md`](plugins/README.md) ([简体中文](plugins/README.zh-CN.md)).
  386. ---
  387. ## Architecture
  388. ```
  389. ┌────────────────── browser (Next.js 16) / Electron shell ──────────────┐
  390. │ chat · file workspace · iframe preview · settings · import · MCP │
  391. └──────────────┬─────────────────────────────────────┬─────────────────┘
  392. │ /api/* │
  393. ▼ ▼
  394. ┌─────────────────────────────────┐ /api/proxy/{provider}/stream (SSE)
  395. │ local daemon (Express+SQLite) │ ─→ any OpenAI-compatible BYOK,
  396. │ │ SSRF-guarded at the edge
  397. │ /api/skills /api/design-templates /api/plugins │
  398. │ /api/design-systems │
  399. │ /api/chat (SSE) /api/proxy/* │
  400. │ /api/projects/:id/files/... │
  401. │ /api/artifacts/{save,lint} │
  402. │ /api/import/claude-design │
  403. │ MCP stdio server │
  404. └─────────┬───────────────────────┘
  405. │ spawn(cli, [...], { cwd: managed project cwd })
  406. ▼
  407. ┌──────────────────────────────────────────────────────────────────┐
  408. │ Local runtime definitions come from runtimes/registry.ts; │
  409. │ the base registry has 27 definitions (including byok-opencode), │
  410. │ backed by 26 distinct local CLI executables because byok-opencode shares │
  411. │ the OpenCode executable. See docs/agent-adapters.md. │
  412. │ composes a functional skill or design template + DESIGN.md; writes files │
  413. └──────────────────────────────────────────────────────────────────┘
  414. ```
  415. | Layer | Stack |
  416. |---|---|
  417. | Frontend | Next.js 16 App Router + React 18 + TypeScript |
  418. | Daemon | Node 24 · Express · SSE streaming · `better-sqlite3` |
  419. | Storage | Before changing or documenting daemon storage paths, you MUST read `AGENTS.md` → **Daemon data directory contract**. This README MUST NOT restate it. |
  420. | Preview | Filesystem runs render canonical project files; BYOK/plain-API runs parse one complete `<artifact>` block into a sandboxed `srcdoc` iframe |
  421. | Export | HTML (inlined) · PDF (browser print) · PPTX (agent-driven) · ZIP · Markdown · MP4 (HyperFrames) |
  422. | Desktop | Electron shell + sandboxed renderer + sidecar IPC (STATUS · EVAL · SCREENSHOT · CONSOLE · CLICK · SHUTDOWN) |
  423. | Lifecycle | One entry point: `pnpm tools-dev` (start / stop / run / status / logs / inspect / check) |
  424. Full architecture → [`docs/architecture.md`](docs/architecture.md). Skill protocol → [`docs/skills-protocol.md`](docs/skills-protocol.md). Agent adapter contract → [`docs/agent-adapters.md`](docs/agent-adapters.md).
  425. ---
  426. ## Roadmap
  427. - [x] Daemon + 27 runtime definitions across 26 distinct coding-agent CLI executables + skill/design-template registries + design-system catalog
  428. - [x] Web app + chat + question form + 5-direction picker + todo progress + sandboxed preview
  429. - [x] 100+ functional skills · separate rendering-template catalog · 151 design-system packages · 5 visual directions · 5 device frames
  430. - [x] SQLite-backed projects · conversations · messages · tabs · templates
  431. - [x] Multi-provider BYOK proxy (`/api/proxy/{anthropic,openai,azure,google,ollama,senseaudio}/stream`) with OpenAI-compatible presets including Atlas Cloud + SSRF guard
  432. - [x] Claude Design ZIP import (`/api/import/claude-design`)
  433. - [x] Sidecar protocol + Electron desktop + IPC automation
  434. - [x] Artifact lint API + 5-dim self-critique pre-emit gate
  435. - [x] **0.8.0** — plugin marketplace infrastructure (261 official plugins, manifest spec, per-agent install scripts)
  436. - [x] **0.9.0** — OpenDesign Cloud (official model service built into the app: zero config, one-click sign-in)
  437. - [x] **0.10.0** — the all-in-one design workspace: the whole craft loop in one window (references → material → interactive editing → motion → handoff)
  438. - [x] **0.11.0** — _The Bazaar_: built in the open — a community marketplace of plugins and design systems anyone can pick from and contribute to
  439. - [x] **0.12.0** — _Brand-backed Design System_: turn the brand you already own into a reusable, portable `DESIGN.md` system
  440. - [x] **0.13.0** — _Stay in Flow_: native session resume, faster model picking, and export straight to screenshot-backed PPTX / PDF
  441. - [x] Published desktop releases — macOS (Apple Silicon + Intel) + Windows (x64)
  442. - [ ] Published Linux desktop release (optional lane) — tracked in [#4368](https://github.com/nexu-io/open-design/issues/4368)
  443. - [ ] Comment-mode surgical edits — partially shipped; reliable targeted patching in progress
  444. - [ ] AI-emitted tweaks panel UX — not yet implemented
  445. - [ ] `npx od init` to scaffold a project with `DESIGN.md`
  446. - [ ] Plugin SDK + `od plugin {add,list,remove,test,publish}` CLI
  447. - [ ] Figma / Pencil → React / Next / Vue migration plugins (alpha)
  448. - [ ] Refresh-existing-codebase plugin (point at a git repo + `DESIGN.md`)
  449. Phased delivery → [`docs/roadmap.md`](docs/roadmap.md).
  450. ---
  451. ## Community
  452. Real people behind every channel.
  453. - 💬 **Discord** — daily chat, plugin sharing, questions → [**discord.gg/mHAjSMV6gz**](https://discord.gg/mHAjSMV6gz)
  454. - 🐦 **X / Twitter** — release notes, milestones, behind the scenes → [**@OpenDesignHQ**](https://x.com/OpenDesignHQ)
  455. - 🗣️ **GitHub Discussions** — deep Q&A, RFCs, "show your work" → [**Discussions**](https://github.com/nexu-io/open-design/discussions)
  456. - 🐛 **GitHub Issues** — bug reports, feature requests → [**Issues**](https://github.com/nexu-io/open-design/issues)
  457. The [`good-first-issue`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and [`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels are the easiest way in.
  458. ---
  459. ## Contributing
  460. OpenDesign keeps moving because contributors — designers, engineers, prompt authors — keep showing up. Many of the most-used skills, design systems, and plugins were written by people outside the core team.
  461. ### 🎯 Where to start (max leverage, min change)
  462. | Want to ship… | How | Where |
  463. |---|---|---|
  464. | A new functional **skill** | Drop a folder with `SKILL.md` + optional `assets/` + `references/` | [`skills/`](skills/) · spec in [`docs/skills-protocol.md`](docs/skills-protocol.md) |
  465. | A new rendering **design template** | Add a renderable `SKILL.md` bundle | [`design-templates/`](design-templates/) |
  466. | A new **design system** | Drop a package centered on `DESIGN.md`; add `manifest.json`, `tokens.css`, components, assets, or provenance when needed | [`design-systems/<brand>/`](design-systems/) |
  467. | A new **plugin** | Drop `open-design.json` + the type-specific payload under a category folder | [`plugins/community/`](plugins/community/) · spec in [`plugins/spec/SPEC.md`](plugins/spec/SPEC.md) · agent dev guide in [`plugins/spec/AGENT-DEVELOPMENT.md`](plugins/spec/AGENT-DEVELOPMENT.md) |
  468. | Support a new **coding-agent CLI** | One runtime definition + registry entry; add a parser only for a new wire format | [`apps/daemon/src/runtimes/defs/`](apps/daemon/src/runtimes/defs/) |
  469. | Fix a bug or polish UI | Browse the [`good-first-issue`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label | [Issues →](https://github.com/nexu-io/open-design/issues) |
  470. | Translate the docs | Update the `README.<lang>.md` files | [`TRANSLATIONS.md`](TRANSLATIONS.md) |
  471. ### 🤖 Contributing as an agent
  472. If *you are the agent reading this*, the fastest path is:
  473. ```bash
  474. # 1. Boot locally
  475. git clone https://github.com/nexu-io/open-design.git
  476. cd open-design && corepack enable && pnpm install
  477. pnpm tools-dev run web
  478. # 2. Find a good-first-issue and assign yourself
  479. gh issue list --label "good first issue" --state open --limit 20
  480. gh issue develop <number> # create a branch and worktree
  481. # 3. Make the change, run the checks
  482. pnpm guard && pnpm typecheck
  483. pnpm --filter @open-design/<package> test
  484. # 4. Open the PR
  485. gh pr create --fill
  486. ```
  487. Full agent-friendly contribution flow, code style, and PR bar → [`CONTRIBUTING.md`](CONTRIBUTING.md) ([Deutsch](docs/i18n/CONTRIBUTING.de.md) · [Français](docs/i18n/CONTRIBUTING.fr.md) · [简体中文](docs/i18n/CONTRIBUTING.zh-CN.md) · [日本語](docs/i18n/CONTRIBUTING.ja-JP.md) · [한국어](docs/i18n/CONTRIBUTING.ko.md) · [Português](docs/i18n/CONTRIBUTING.pt-BR.md) · [ภาษาไทย](docs/i18n/CONTRIBUTING.th.md)).
  488. ### 🏅 OpenDesign Fellow program
  489. We're recruiting **OpenDesign Fellows** around the world — Fellows shape the product alongside the core team, represent OpenDesign officially in their region, and grow the community locally, backed by funded support ($1,000 / MR), free LLM credits, and a direct review track. Details → [`MAINTAINERS.md`](MAINTAINERS.md) and the announcement on [Discord](https://discord.gg/mHAjSMV6gz).
  490. ---
  491. ## Maintainers
  492. They carry a lot of the load — daily maintenance, review, and community support.
  493. <table>
  494. <tr>
  495. <td align="center" valign="top" width="200">
  496. <a href="https://github.com/Nagendhra-web">
  497. <img src="https://github.com/Nagendhra-web.png" width="96" alt="@Nagendhra-web" /><br/>
  498. <sub><b>@Nagendhra-web</b></sub>
  499. </a><br/>
  500. <sub>Maintainer</sub>
  501. </td>
  502. <td align="center" valign="top" width="200">
  503. <a href="https://github.com/Sid-Qin">
  504. <img src="https://github.com/Sid-Qin.png" width="96" alt="@Sid-Qin" /><br/>
  505. <sub><b>@Sid-Qin</b></sub>
  506. </a><br/>
  507. <sub>Maintainer</sub>
  508. </td>
  509. <td align="center" valign="top" width="200">
  510. <a href="https://github.com/YOMXXX">
  511. <img src="https://github.com/YOMXXX.png" width="96" alt="@YOMXXX" /><br/>
  512. <sub><b>@YOMXXX</b></sub>
  513. </a><br/>
  514. <sub>Maintainer</sub>
  515. </td>
  516. </tr>
  517. </table>
  518. Maintainer rules, promotion criteria, and the exit protocol → [`MAINTAINERS.md`](MAINTAINERS.md) (also [Deutsch](docs/i18n/MAINTAINERS.de.md) · [Français](docs/i18n/MAINTAINERS.fr.md) · [简体中文](docs/i18n/MAINTAINERS.zh-CN.md) · [日本語](docs/i18n/MAINTAINERS.ja-JP.md) · [한국어](docs/i18n/MAINTAINERS.ko.md) · [Português](docs/i18n/MAINTAINERS.pt-BR.md) · [ภาษาไทย](docs/i18n/MAINTAINERS.th.md)).
  519. ## Contributors
  520. Thanks to everyone who has taken part — code, docs, feedback, a sharp issue, a new skill, a new design system.
  521. <a href="https://github.com/nexu-io/open-design/graphs/contributors">
  522. <img src="https://contrib.rocks/image?repo=nexu-io/open-design&max=500&columns=20&anon=1&cache_bust=2026-08-04" alt="OpenDesign contributors" />
  523. </a>
  524. ---
  525. ## Repository activity
  526. <picture>
  527. <img alt="OpenDesign — repository metrics" src="https://repo-assets.open-design.ai/resources/images/github-metrics.svg" />
  528. </picture>
  529. The SVG above is regenerated daily by [`.github/workflows/metrics.yml`](.github/workflows/metrics.yml) using [`lowlighter/metrics`](https://github.com/lowlighter/metrics).
  530. ---
  531. ## Star us
  532. <p align="center">
  533. <a href="https://github.com/nexu-io/open-design"><img src="https://repo-assets.open-design.ai/resources/images/star-us.png" alt="Star OpenDesign on GitHub — github.com/nexu-io/open-design" width="100%" /></a>
  534. </p>
  535. If this saved you thirty minutes, give it a ★. Stars don't pay rent — but they tell the next designer, agent, and contributor that this experiment is worth their attention. One click, three seconds, a real signal.
  536. <a href="https://star-history.dera.page/#nexu-io/open-design&Date">
  537. <picture>
  538. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-08-04" />
  539. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-08-04" />
  540. <img alt="OpenDesign star history" src="https://star-history.dera.page/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-08-04" />
  541. </picture>
  542. </a>
  543. ---
  544. ## References & lineage
  545. | Project | Role |
  546. |---|---|
  547. | [`alchaincyf/huashu-design`](https://github.com/alchaincyf/huashu-design) | The design-philosophy compass — junior-designer workflow, brand-asset protocol, anti-AI-slop checklist, five-dimensional critique. |
  548. | [`op7418/guizang-ppt-skill`](https://github.com/op7418/guizang-ppt-skill) | The magazine-style web PPT skill, bundled verbatim under [`design-templates/guizang-ppt/`](design-templates/guizang-ppt/). Default for deck mode. |
  549. | [`lewislulu/html-ppt-skill`](https://github.com/lewislulu/html-ppt-skill) | The HTML PPT Studio family — 15 deck templates, 36 themes, 31 page layouts, animation runtime, magnetic-card presenter mode. |
  550. | [`OpenCoworkAI/open-codesign`](https://github.com/OpenCoworkAI/open-codesign) | UX patterns we borrow (streaming-artifact loop, sandboxed iframe, live agent panel). |
  551. | [`multica-ai/multica`](https://github.com/multica-ai/multica) | The daemon + adapter architecture — PATH-scan agent detection, local daemon as the only privileged process. |
  552. | [`VoltAgent/awesome-design-md`](https://github.com/VoltAgent/awesome-design-md) | Historical source of the original 9-section `DESIGN.md` schema and 70 upstream-derived systems; current packages may extend that baseline. |
  553. | [`bergside/awesome-design-skills`](https://github.com/bergside/awesome-design-skills) | Source of the 57 design skills added under `design-systems/`. |
  554. | [`heygen-com/hyperframes`](https://github.com/heygen-com/hyperframes) | The HTML→MP4 motion-graphics framework, integrated as the first-class `hyperframes-html` in OpenDesign. |
  555. | [Claude Code skills][skill] | The `SKILL.md` convention we adopt verbatim. |
  556. Detailed provenance → [`docs/references.md`](docs/references.md).
  557. [skill]: https://docs.anthropic.com/en/docs/claude-code/skills
  558. ## License
  559. Apache-2.0. Bundled skills and templates with their own `LICENSE` files retain those licenses, including `design-templates/guizang-ppt/` (MIT, [@op7418](https://github.com/op7418)), `design-templates/html-ppt/` (MIT, [@lewislulu](https://github.com/lewislulu)), and `skills/web-clone/` (MIT, [@Jane-xiaoer](https://github.com/Jane-xiaoer)).
.claude/skills/od-contribute/install.sh · Bundled script · 136 lines · 1 finding marked
  1. #!/usr/bin/env bash
  2. # OD Contribute installer — self-bootstrapping.
  3. # Fetches the latest od-contribute skill from nexu-io/open-design and installs
  4. # it into every supported AI agent's home directory.
  5. #
  6. # Two ways to run this:
  7. #
  8. # 1) Tell your AI agent (Claude Code / Codex / Cursor / etc.) in the chat:
  9. #
  10. # curl -sSL https://raw.githubusercontent.com/nexu-io/open-design/main/.claude/skills/od-contribute/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 10 on GitHub
  11. #
  12. # The agent's Bash tool runs this. You never open a terminal yourself.
  13. #
  14. # 2) Or paste that same one-liner into a terminal directly, if you prefer.
  15. #
  16. # Targets installed:
  17. # ~/.claude/skills/od-contribute/ Claude Code (native skill format)
  18. # ~/.claude/commands/od-contribute.md Claude Code slash command
  19. # ~/.agents/skills/od-contribute/ Codex CLI (canonical path)
  20. # ~/.codex/skills/od-contribute/ Codex CLI (legacy, only if ~/.codex exists)
  21. #
  22. # Override the source branch with OD_CONTRIBUTE_BRANCH=feat/foo (default: main).
  23. set -euo pipefail
  24. REPO="nexu-io/open-design"
  25. BRANCH="${OD_CONTRIBUTE_BRANCH:-main}"
  26. cyan() { printf '\033[36m%s\033[0m\n' "$*"; }
  27. green() { printf '\033[32m%s\033[0m\n' "$*"; }
  28. gray() { printf '\033[90m%s\033[0m\n' "$*"; }
  29. die() { printf '\033[31m[error]\033[0m %s\n' "$*" >&2; exit 1; }
  30. cyan "Installing OD Contribute skill from ${REPO}@${BRANCH}..."
  31. command -v curl >/dev/null 2>&1 || die "curl is required."
  32. command -v tar >/dev/null 2>&1 || die "tar is required."
  33. TMPDIR="$(mktemp -d)"
  34. trap 'rm -rf "$TMPDIR"' EXIT
  35. # Tarball download — no `git clone` needed (works in env without git).
  36. TARBALL="$TMPDIR/repo.tar.gz"
  37. curl -fsSL "https://github.com/${REPO}/archive/refs/heads/${BRANCH}.tar.gz" -o "$TARBALL" \
  38. || die "failed to fetch ${REPO}@${BRANCH} (branch may not exist)"
  39. # Extract just the two paths we need. GitHub tarballs name the root dir
  40. # <repo>-<branch>/, with slashes in branch names converted to dashes.
  41. TARBALL_ROOT="open-design-${BRANCH//\//-}"
  42. tar -xzf "$TARBALL" -C "$TMPDIR" \
  43. "${TARBALL_ROOT}/.claude/skills/od-contribute" \
  44. "${TARBALL_ROOT}/.claude/commands/od-contribute.md" \
  45. 2>/dev/null || die "skill files not found in tarball — branch may have different layout"
  46. SKILL_SRC="$TMPDIR/${TARBALL_ROOT}/.claude/skills/od-contribute"
  47. CMD_SRC="$TMPDIR/${TARBALL_ROOT}/.claude/commands/od-contribute.md"
  48. [[ -f "$SKILL_SRC/SKILL.md" ]] || die "SKILL.md missing at expected path"
  49. [[ -f "$CMD_SRC" ]] || die "slash command missing at expected path"
  50. install_skill_to() {
  51. local dest="$1" label="$2"
  52. # Preserve user-local state across reinstall/upgrade. Re-running this script
  53. # is the documented upgrade path ("re-run to pull the latest skill from
  54. # main"), so anything the user wrote here that ISN'T part of the skill
  55. # itself must survive `rm -rf`. Today that's just `.gh-token` (sandboxed
  56. # agents like Codex.app / Cursor write a GitHub token here when they can't
  57. # reach the macOS keychain — see check-prereqs.sh's hint and config.sh's
  58. # fallback). Add new state filenames to PRESERVE if we ever introduce more.
  59. local PRESERVE=(.gh-token)
  60. local stash=""
  61. local f
  62. for f in "${PRESERVE[@]}"; do
  63. if [[ -f "$dest/$f" ]]; then
  64. [[ -z "$stash" ]] && stash="$(mktemp -d)"
  65. cp -p "$dest/$f" "$stash/$f"
  66. fi
  67. done
  68. rm -rf "$dest"
  69. mkdir -p "$dest"
  70. cp -R "$SKILL_SRC/." "$dest/"
  71. # Restore preserved state. The mode preservation (`cp -p` above + this
  72. # explicit chmod) keeps tokens at 600.
  73. if [[ -n "$stash" ]]; then
  74. for f in "${PRESERVE[@]}"; do
  75. if [[ -f "$stash/$f" ]]; then
  76. cp -p "$stash/$f" "$dest/$f"
  77. chmod 600 "$dest/$f" 2>/dev/null || true
  78. fi
  79. done
  80. rm -rf "$stash"
  81. fi
  82. # Ensure scripts retain executable bit (tar usually preserves; defense in depth).
  83. find "$dest" -name '*.sh' -exec chmod +x {} + 2>/dev/null || true
  84. green " ✓ $label"
  85. gray " $dest"
  86. }
  87. # --- Claude Code (native, always install) -----------------------------------
  88. install_skill_to "$HOME/.claude/skills/od-contribute" "Claude Code skill"
  89. mkdir -p "$HOME/.claude/commands"
  90. cp "$CMD_SRC" "$HOME/.claude/commands/od-contribute.md"
  91. green " ✓ Claude Code slash command (/od-contribute)"
  92. gray " $HOME/.claude/commands/od-contribute.md"
  93. # --- Codex CLI (canonical) --------------------------------------------------
  94. install_skill_to "$HOME/.agents/skills/od-contribute" "Codex CLI skill (~/.agents/skills/)"
  95. # --- Codex CLI (legacy) — only if user already has Codex --------------------
  96. if [[ -d "$HOME/.codex" ]]; then
  97. install_skill_to "$HOME/.codex/skills/od-contribute" "Codex CLI skill (legacy ~/.codex/skills/)"
  98. fi
  99. echo
  100. green "Done."
  101. echo
  102. cyan "How to use it:"
  103. cat <<'EOF'
  104. In Claude Code: type /od-contribute in any chat.
  105. In Codex CLI: type @od-contribute or pick "OpenDesign — Contribute" from /skills.
  106. In other agents: ask the agent to follow ~/.claude/skills/od-contribute/SKILL.md
  107. The skill walks you through one of:
  108. * shipping a Skill or Design System you made with OpenDesign
  109. * translating a doc to a new language
  110. * fixing a typo or writing a use-case blog
  111. * reporting a clean bug
  112. Need help? OpenDesign Discord: https://discord.gg/qhbcCH8Am4
  113. EOF
design-templates/last30days/scripts/lib/setup_wizard.py · Bundled script · 535 lines · 1 finding marked
  1. """First-run setup wizard for last30days.
  2. Detects first run, performs auto-setup (cookie extraction + yt-dlp check),
  3. and writes configuration. The actual wizard UI is SKILL.md-driven (the LLM
  4. presents it), but this module provides the detection and setup actions.
  5. """
  6. import json
  7. import logging
  8. import shutil
  9. import subprocess
  10. import time
  11. from pathlib import Path
  12. from typing import Any, Dict, Optional, Tuple
  13. from urllib.error import HTTPError, URLError
  14. from urllib.request import Request, urlopen
  15. logger = logging.getLogger(__name__)
  16. def is_first_run(config: Dict[str, Any]) -> bool:
  17. """Return True if the setup wizard has not been completed.
  18. Checks for SETUP_COMPLETE in the config dict. If it's not set
  19. (None or empty string), the user hasn't gone through setup yet.
  20. """
  21. return not config.get("SETUP_COMPLETE")
  22. def run_auto_setup(config: Dict[str, Any]) -> Dict[str, Any]:
  23. """Perform the auto-setup actions.
  24. - Runs cookie extraction in auto mode for all registered domains
  25. - Checks if yt-dlp is installed
  26. Returns:
  27. Dict with keys:
  28. cookies_found: {source_name: browser_name} for each source where cookies were found
  29. ytdlp_installed: bool
  30. env_written: bool (always False here — caller writes config separately)
  31. """
  32. from . import cookie_extract
  33. from .env import COOKIE_DOMAINS
  34. cookies_found: Dict[str, str] = {}
  35. for source_name, spec in COOKIE_DOMAINS.items():
  36. domain = spec["domain"]
  37. cookie_names = spec["cookies"]
  38. try:
  39. result = cookie_extract.extract_cookies_with_source("auto", domain, cookie_names)
  40. except Exception as exc:
  41. logger.debug("Cookie extraction failed for %s: %s", source_name, exc)
  42. continue
  43. if result is not None:
  44. _cookies, browser_name = result
  45. cookies_found[source_name] = browser_name
  46. # Check yt-dlp availability and install via Homebrew if missing
  47. ytdlp_action: str
  48. if shutil.which("yt-dlp") is not None:
  49. ytdlp_installed = True
  50. ytdlp_action = "already_installed"
  51. elif shutil.which("brew") is not None:
  52. brew_stderr = ""
  53. try:
  54. proc = subprocess.run(
  55. ["brew", "install", "yt-dlp"],
  56. capture_output=True, text=True, timeout=120,
  57. )
  58. if proc.returncode == 0:
  59. ytdlp_installed = True
  60. ytdlp_action = "installed"
  61. else:
  62. ytdlp_installed = False
  63. ytdlp_action = "install_failed"
  64. brew_stderr = proc.stderr
  65. logger.warning("brew install yt-dlp failed: %s", proc.stderr)
  66. except Exception as exc:
  67. ytdlp_installed = False
  68. ytdlp_action = "install_failed"
  69. brew_stderr = str(exc)
  70. logger.warning("brew install yt-dlp exception: %s", exc)
  71. else:
  72. ytdlp_installed = False
  73. ytdlp_action = "no_homebrew"
  74. results: Dict[str, Any] = {
  75. "cookies_found": cookies_found,
  76. "ytdlp_installed": ytdlp_installed,
  77. "ytdlp_action": ytdlp_action,
  78. "env_written": False,
  79. }
  80. if ytdlp_action == "install_failed":
  81. results["ytdlp_stderr"] = brew_stderr
  82. return results
  83. def write_setup_config(env_path: Path, from_browser: str = "auto") -> bool:
  84. """Write SETUP_COMPLETE and FROM_BROWSER to the .env file.
  85. Creates the file and parent directories if needed.
  86. Appends to existing file without overwriting existing keys.
  87. Args:
  88. env_path: Path to the .env file (e.g. ~/.config/last30days/.env)
  89. from_browser: Browser extraction mode to write (default: "auto")
  90. Returns:
  91. True if config was written successfully, False on error.
  92. """
  93. try:
  94. env_path = Path(env_path)
  95. env_path.parent.mkdir(parents=True, exist_ok=True)
  96. # Read existing content to avoid overwriting keys
  97. existing_keys: set = set()
  98. existing_content = ""
  99. if env_path.exists():
  100. existing_content = env_path.read_text(encoding="utf-8")
  101. for line in existing_content.splitlines():
  102. stripped = line.strip()
  103. if stripped and not stripped.startswith("#") and "=" in stripped:
  104. key = stripped.split("=", 1)[0].strip()
  105. existing_keys.add(key)
  106. lines_to_add = []
  107. if "SETUP_COMPLETE" not in existing_keys:
  108. lines_to_add.append("SETUP_COMPLETE=true")
  109. if "FROM_BROWSER" not in existing_keys:
  110. lines_to_add.append(f"FROM_BROWSER={from_browser}")
  111. if not lines_to_add:
  112. return True # Nothing to write, already configured
  113. # Ensure trailing newline before appending
  114. with open(env_path, "a", encoding="utf-8") as f:
  115. if existing_content and not existing_content.endswith("\n"):
  116. f.write("\n")
  117. f.write("\n".join(lines_to_add) + "\n")
  118. return True
  119. except OSError as exc:
  120. logger.error("Failed to write setup config to %s: %s", env_path, exc)
  121. return False
  122. def get_setup_status_text(results: Dict[str, Any]) -> str:
  123. """Return a human-readable summary of auto-setup results.
  124. Args:
  125. results: Dict from run_auto_setup()
  126. Returns:
  127. Multi-line status text.
  128. """
  129. lines = []
  130. lines.append("Setup complete! Here's what I found:")
  131. lines.append("")
  132. cookies_found = results.get("cookies_found", {})
  133. if cookies_found:
  134. for source, browser in cookies_found.items():
  135. lines.append(f" - {source.upper()} cookies found in {browser}")
  136. else:
  137. lines.append(" - No browser cookies found for X/Twitter")
  138. ytdlp_action = results.get("ytdlp_action", "")
  139. if ytdlp_action == "installed":
  140. lines.append(" - Installed yt-dlp via Homebrew")
  141. elif ytdlp_action == "install_failed":
  142. lines.append(" - yt-dlp install failed \u2014 run `brew install yt-dlp` manually")
  143. elif ytdlp_action == "no_homebrew":
  144. lines.append(" - yt-dlp not found. Install Homebrew first, then: brew install yt-dlp")
  145. elif ytdlp_action == "already_installed":
  146. lines.append(" - yt-dlp already installed")
  147. elif results.get("ytdlp_installed", False):
  148. lines.append(" - yt-dlp is installed (YouTube search ready)")
  149. else:
  150. lines.append(" - yt-dlp not found (install with: brew install yt-dlp)")
  151. env_written = results.get("env_written", False)
  152. if env_written:
  153. lines.append("")
  154. lines.append("Configuration saved. Future runs will auto-detect your browsers.")
  155. return "\n".join(lines)
  156. # ---------------------------------------------------------------------------
  157. # OpenClaw server-side setup (no browser, JSON output)
  158. # ---------------------------------------------------------------------------
  159. _OPENCLAW_KEY_NAMES = [
  160. "SCRAPECREATORS_API_KEY",
  161. "XAI_API_KEY",
  162. "BRAVE_API_KEY",
  163. "EXA_API_KEY",
  164. "SERPER_API_KEY",
  165. "OPENAI_API_KEY",
  166. "AUTH_TOKEN",
  167. ]
  168. def run_openclaw_setup(config: Dict[str, Any]) -> Dict[str, Any]:
  169. """Server-side setup probe: no cookies, just tool + key availability.
  170. Returns a dict suitable for JSON output to stdout so that SKILL.md
  171. can present appropriate options to the user.
  172. """
  173. yt_dlp = shutil.which("yt-dlp") is not None
  174. node = shutil.which("node") is not None
  175. python3 = shutil.which("python3") is not None
  176. keys: Dict[str, bool] = {}
  177. for key_name in _OPENCLAW_KEY_NAMES:
  178. short = key_name.lower().replace("_api_key", "").replace("_key", "").replace("_token", "")
  179. # Normalize: AUTH_TOKEN -> auth, SCRAPECREATORS_API_KEY -> scrapecreators
  180. keys[short] = bool(config.get(key_name))
  181. # Determine x_method
  182. if config.get("XAI_API_KEY"):
  183. x_method: Optional[str] = "xai"
  184. elif config.get("AUTH_TOKEN") and config.get("CT0"):
  185. x_method = "cookies"
  186. else:
  187. x_method = None
  188. return {
  189. "yt_dlp": yt_dlp,
  190. "node": node,
  191. "python3": python3,
  192. "keys": keys,
  193. "x_method": x_method,
  194. }
  195. # ---------------------------------------------------------------------------
  196. # PAT auth flow (GitHub token via ScrapeCreators)
  197. # ---------------------------------------------------------------------------
  198. _PAT_BASE = "https://api.scrapecreators.com/v1/github/pat"
  199. def auth_with_pat(github_token: str) -> Optional[Dict[str, Any]]:
  200. """Authenticate with ScrapeCreators using a GitHub PAT.
  201. POSTs the token to the PAT auth endpoint. ScrapeCreators verifies it
  202. against GitHub's API, creates/finds the account, and returns an API key.
  203. Returns:
  204. Dict with api_key, github_username, etc. on success, None on failure.
  205. """
  206. try:
  207. req = Request(f"{_PAT_BASE}/auth", data=b"", method="POST")
  208. req.add_header("Authorization", f"Bearer {github_token}")
  209. with urlopen(req, timeout=15) as resp:
  210. data = json.loads(resp.read())
  211. except HTTPError as exc:
  212. if exc.code == 422:
  213. logger.warning("PAT auth: insufficient scope — user needs user:email")
  214. else:
  215. logger.warning("PAT auth failed: %s", exc)
  216. return None
  217. except (URLError, OSError) as exc:
  218. logger.warning("PAT auth request failed: %s", exc)
  219. return None
  220. if not data.get("api_key"):
  221. logger.warning("PAT auth returned no api_key: %s", data)
  222. return None
  223. return data
  224. # ---------------------------------------------------------------------------
  225. # Device auth flow (GitHub OAuth via ScrapeCreators)
  226. # ---------------------------------------------------------------------------
  227. _DEVICE_BASE = "https://api.scrapecreators.com/v1/github/device"
  228. def run_device_auth() -> Optional[Tuple[str, str, str, int]]:
  229. """Start the device authorization flow.
  230. POSTs to the ScrapeCreators device/code endpoint.
  231. Returns:
  232. (device_code, user_code, verification_uri, interval) on success,
  233. None on failure.
  234. """
  235. try:
  236. body = json.dumps({}).encode()
  237. req = Request(f"{_DEVICE_BASE}/code", data=body, method="POST")
  238. req.add_header("Content-Type", "application/json")
  239. with urlopen(req, timeout=15) as resp:
  240. data = json.loads(resp.read())
  241. except (HTTPError, URLError, OSError) as exc:
  242. logger.warning("Device auth code request failed: %s", exc)
  243. return None
  244. device_code = data.get("device_code")
  245. user_code = data.get("user_code")
  246. verification_uri = data.get("verification_uri")
  247. interval = data.get("interval", 5)
  248. if not device_code or not user_code:
  249. logger.warning("Device auth returned incomplete response: %s", data)
  250. return None
  251. return (device_code, user_code, verification_uri or "", interval)
  252. def poll_device_auth(
  253. device_code: str,
  254. interval: int,
  255. timeout: int = 300,
  256. user_code: str = "",
  257. clipboard_ok: bool = False,
  258. ) -> Optional[str]:
  259. """Poll for an access token after the user authorizes the device.
  260. Args:
  261. device_code: The device_code from run_device_auth().
  262. interval: Polling interval in seconds.
  263. timeout: Maximum time to poll in seconds.
  264. user_code: The user code to remind about during polling.
  265. clipboard_ok: Whether the code was copied to clipboard.
  266. Returns:
  267. access_token on success, None on timeout or failure.
  268. """
  269. import sys
  270. deadline = time.time() + timeout
  271. last_reminder = time.time()
  272. reminder_count = 0
  273. max_reminders = 4
  274. reminder_interval = 30 # seconds between reminders
  275. while time.time() < deadline:
  276. time.sleep(interval)
  277. # Periodic reminder of the code while waiting
  278. if (
  279. user_code
  280. and reminder_count < max_reminders
  281. and time.time() - last_reminder >= reminder_interval
  282. ):
  283. clipboard_hint = " (on your clipboard)" if clipboard_ok else ""
  284. print(
  285. f" Still waiting... Your code: {user_code}{clipboard_hint}",
  286. file=sys.stderr,
  287. flush=True,
  288. )
  289. last_reminder = time.time()
  290. reminder_count += 1
  291. try:
  292. body = json.dumps({"device_code": device_code}).encode()
  293. req = Request(f"{_DEVICE_BASE}/token", data=body, method="POST")
  294. req.add_header("Content-Type", "application/json")
  295. with urlopen(req, timeout=15) as resp:
  296. data = json.loads(resp.read())
  297. except HTTPError as exc:
  298. if exc.code in (400, 403, 428):
  299. continue
  300. logger.warning("Device auth poll error: %s", exc)
  301. return None
  302. except (URLError, OSError):
  303. continue
  304. if data.get("access_token"):
  305. return data["access_token"]
  306. error = data.get("error")
  307. if error == "slow_down":
  308. interval = min(interval + 2, 30)
  309. continue
  310. if error == "authorization_pending":
  311. continue
  312. if error in ("expired_token", "access_denied"):
  313. logger.warning("Device auth failed: %s", error)
  314. return None
  315. return None
  316. def fetch_api_key(access_token: str) -> Optional[str]:
  317. """Fetch the ScrapeCreators API key using the GitHub access token.
  318. GETs the device/profile endpoint with Bearer auth.
  319. Returns:
  320. api_key string on success, None on failure.
  321. """
  322. try:
  323. req = Request(f"{_DEVICE_BASE}/profile")
  324. req.add_header("Authorization", f"Bearer {access_token}")
  325. with urlopen(req, timeout=15) as resp:
  326. data = json.loads(resp.read())
  327. except (HTTPError, URLError, OSError) as exc:
  328. logger.warning("Failed to fetch API key: %s", exc)
  329. return None
  330. return data.get("api_key")
  331. def run_full_device_auth(timeout: int = 300) -> Dict[str, Any]:
  332. """Run the complete GitHub device auth flow and return JSON-serializable result.
  333. Chains: start device flow -> open browser -> poll -> fetch API key.
  334. Designed to be called from the CLI and have its stdout parsed by the LLM.
  335. Returns:
  336. Dict with status and relevant fields:
  337. - {"status": "success", "api_key": "sc_...", "user_code": "ABCD-1234"}
  338. - {"status": "error", "message": "..."}
  339. - {"status": "timeout", "user_code": "ABCD-1234"}
  340. - {"status": "denied"}
  341. """
  342. import webbrowser
  343. # Step 1: Start device flow
  344. result = run_device_auth()
  345. if result is None:
  346. return {"status": "error", "message": "Failed to start device auth flow"}
  347. device_code, user_code, verification_uri, interval = result
  348. import sys
  349. # Step 2: Copy code to clipboard BEFORE opening browser
  350. clipboard_ok = False
  351. if sys.platform == "darwin":
  352. try:
  353. subprocess.run(
  354. ["pbcopy"], input=user_code.encode(), check=True, timeout=5,
  355. )
  356. clipboard_ok = True
  357. except Exception:
  358. pass # pbcopy unavailable or failed, fall through
  359. # Step 3: Show code prominently, then open browser
  360. clipboard_hint = " (copied to clipboard)" if clipboard_ok else ""
  361. code_line = f" Your code: {user_code}{clipboard_hint}"
  362. action_line = " Paste it on the GitHub page that just opened"
  363. width = max(len(code_line), len(action_line)) + 2
  364. border = "-" * width
  365. print(f"\n+{border}+", file=sys.stderr)
  366. print(f"|{code_line.ljust(width)}|", file=sys.stderr)
  367. print(f"|{action_line.ljust(width)}|", file=sys.stderr)
  368. print(f"+{border}+", file=sys.stderr)
  369. if verification_uri:
  370. try:
  371. webbrowser.open(verification_uri)
  372. except Exception:
  373. print(f"Open: {verification_uri}", file=sys.stderr)
  374. print("Waiting for authorization...", file=sys.stderr, flush=True)
  375. # Step 4: Poll for token (with periodic code reminders)
  376. access_token = poll_device_auth(
  377. device_code, interval, timeout=timeout,
  378. user_code=user_code, clipboard_ok=clipboard_ok,
  379. )
  380. if access_token is None:
  381. return {"status": "timeout", "user_code": user_code, "clipboard_ok": clipboard_ok}
  382. # Step 4: Fetch API key
  383. api_key = fetch_api_key(access_token)
  384. if api_key is None:
  385. return {
  386. "status": "error",
  387. "message": "Authorized but failed to fetch API key",
  388. "clipboard_ok": clipboard_ok,
  389. }
  390. return {"status": "success", "method": "device", "api_key": api_key, "user_code": user_code, "clipboard_ok": clipboard_ok}
  391. # ---------------------------------------------------------------------------
  392. # Unified GitHub auth: PAT first, device flow fallback
  393. # ---------------------------------------------------------------------------
  394. def run_github_auth(timeout: int = 300) -> Dict[str, Any]:
  395. """Try PAT auth via gh CLI, fall back to device flow.
  396. 1. Check for `gh` CLI
  397. 2. If found, run `gh auth token` to get a PAT
  398. 3. POST PAT to ScrapeCreators — if it works, done
  399. 4. If PAT fails for any reason, fall through to device flow
  400. Returns JSON-serializable dict with status, method, and api_key.
  401. """
  402. import sys
  403. # Step 1: Try PAT via gh CLI
  404. gh_path = shutil.which("gh")
  405. if gh_path:
  406. try:
  407. result = subprocess.run(
    • Warning: Runs `gh auth token` to read the user's GitHub token and POSTs it to api.scrapecreators.com, a third-party service, to get an API key. Sign-up could use the browser device flow instead of sending an existing token.
    • Line 507 on GitHub
  408. ["gh", "auth", "token"],
  409. capture_output=True, text=True, timeout=10,
  410. )
  411. if result.returncode == 0 and result.stdout.strip():
  412. token = result.stdout.strip()
  413. print("Found gh CLI — trying PAT auth...", file=sys.stderr)
  414. pat_result = auth_with_pat(token)
  415. if pat_result and pat_result.get("api_key"):
  416. return {
  417. "status": "success",
  418. "method": "pat",
  419. "api_key": pat_result["api_key"],
  420. "github_username": pat_result.get("github_username", ""),
  421. }
  422. # PAT failed — might be insufficient scope
  423. print(
  424. "PAT auth didn't work (scope or endpoint issue). "
  425. "Falling back to GitHub device flow...",
  426. file=sys.stderr,
  427. )
  428. except Exception as exc:
  429. logger.debug("gh auth token failed: %s", exc)
  430. # Step 2: Fall back to device flow
  431. if not gh_path:
  432. print("gh CLI not found — using GitHub device flow...", file=sys.stderr)
  433. return run_full_device_auth(timeout=timeout)

Ratings and comments

Sign in to rate this skill.

Sign in

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