mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00

🎨 Local-first, open-source alternative to Anthropic's Claude Design. ⚡ 19 Skills · ✨ 71 brand-grade Design Systems 🖼 Generate web · desktop · mobile prototypes · slides · images · videos · HyperFrames 📦 Sandboxed preview · HTML/PDF/PPTX/MP4 export 🤖 Runs on Claude Code / Codex / Cursor / Gemini / OpenCode / Qwen / Copilot / Hermes / Kimi CLI.

Find a file

Bryan A 587c783dc0 feat(web): add Finalize design package + Continue in CLI buttons (#451 ) (#974 ) * feat(daemon): expose resolvedDir on GET /api/projects/:id (#451 prereq) Native projects (no metadata.baseDir) live at <projects root>/<id>, where projects root is daemon-side state. The web client cannot reconstruct an absolute path on its own, and shell.openPath on a relative path is undefined behavior. Without resolvedDir, the upcoming Continue in CLI button (#451) would render permanently disabled for native projects. Mirrors PR #832's pattern of exposing designMdPath in its response. Computed via the existing resolveProjectDir(...) helper. No behavior change to existing callers; they ignore the new field. Adds ProjectDetailResponse contract type and a focused projects-routes test covering imported-folder, native, and unknown-id paths. * feat(web): add parseProvenance helper for DESIGN.md staleness checks Pure helper that extracts Project ID, design system, current artifact, transcript message count, and generated UTC timestamp from the `## Provenance` section emitted by the daemon's finalize synthesis prompt (apps/daemon/src/finalize-design.ts). Used by useDesignMdState to derive the Continue in CLI button's stale/fresh state without an additional daemon endpoint. Handles missing section, "none" sentinels for design system / artifact, and malformed timestamps without throwing. Tests cover all four branches. * feat(web): add buildClipboardPrompt template for Continue in CLI Inline single-source-of-truth template per #451 spec §3.4. Names the project, the working directory, and the DESIGN.md-first operating contract for the receiving `claude` CLI session. Trailing TODO is the blank task slot the issue body specifies — left empty so the user fills it in before submitting. Also lands the shared copyToClipboard helper (jsdom-safe canonical path + execCommand fallback) so the new button and any future caller share one fallback path, mirroring the inline pattern in FileViewer.tsx. Tests cover happy-path field rendering, "none"/"unknown" sentinels when DESIGN.md fields are absent, and both clipboard branches. * feat(web): add useProjectDetail + useDesignMdState hooks useProjectDetail wraps GET /api/projects/:id, surfacing the resolvedDir field and falling back to metadata.baseDir for older daemons that don't include it. Continue in CLI needs an absolute working directory so the desktop bridge can openPath it; the web client never reconstructs the path itself. useDesignMdState fetches the project's file list, downloads DESIGN.md when present, parses the Provenance section, and computes a stale verdict by comparing the recorded generatedAt against the max mtime of non-DESIGN.md files and the max conversation updatedAt. Drives the button's three-state UI (disabled / fresh / stale) without a daemon-side endpoint. Tests cover happy path, fallback, and both stale branches plus the pure computeStale helper for the null-timestamp edge case. * feat(web): add useFinalizeProject hook with cancel + error-code mapping Wraps POST /api/projects/:id/finalize/anthropic for the Finalize design package button. Three concerns: 1. Lifecycle: idle → pending → success \| error. Double-clicking the button aborts the prior in-flight request before starting a new one so the daemon never sees stacked finalize calls per project. 2. Cancellation: AbortController plumbed through fetch + a 130 s timer (daemon timeout 120 s + 10 s buffer). Cancel returns to idle cleanly — it's a user gesture, not an error surface. 3. Daemon error mapping: when the response is non-OK, body.error.code drives the canonical user-facing toast string (table covers all 7 codes the daemon emits today plus a network-error catch-all). body.error.details, when a string, surfaces alongside the category message so account-usage-cap responses (Anthropic 400 → UPSTREAM_UNAVAILABLE) can show the upstream's own reason instead of just the daemon's category label — committed to lefarcen on #450 verification reply. Tests cover request body shape, all 8 error codes via it.each, the network-error path, the details-surfacing branch, the cancel ⇒ idle flow, and the unknown-code → catch-all message branch. * feat(web): add useTerminalLaunch with electron/web detection Capability-detected wrapper around window.electronAPI.openPath. On desktop the bridge forwards to shell.openPath, which opens the OS file manager at the project working directory (per Electron's contract for directory paths — it is NOT a terminal launcher; spawning a terminal application is deferred per #451 Non-goals). On browser builds the hook reports web-fallback so the caller renders a manual-instruction toast naming the working directory. Treats any non-empty string return from shell.openPath as ok: false so platform-specific failures surface the manual fallback toast. Behavior is exercised end-to-end by the upcoming ContinueInCliButton tests. * feat(desktop): expose shell.openPath via electronAPI bridge Adds an openPath bridge method that the Continue in CLI button (#451) uses to surface the project working directory in the OS file manager. shell.openPath is part of Electron's contract and resolves to '' on success / a non-empty error string on failure; the IPC handler forwards the result so the renderer can decide between the success toast and the manual fallback toast without a separate error channel. Empty / non-string inputs short-circuit to a self-describing error string so the renderer never needs to worry about undefined-input crashes from the main process. Web side: extracts Window.electronAPI into a single global declaration at apps/web/src/types/electron.d.ts so future bridge methods land in one place. Two pre-existing inline declare-global blocks (NewProjectPanel.tsx, providers/registry.ts) are deleted in favor of that single source of truth — the inline ones each carried a partial shape of the bridge and were diverging from the desktop preload. * feat(web): add FinalizeDesignButton, ContinueInCliButton, ProjectActionsToolbar Project-level toolbar that hosts the two new actions from #451. Mounted between AppChromeHeader and the chat/workspace split (wiring lands in the next commit). Per-file actions (Export PDF/PPTX/ZIP, Deploy) stay in the FileViewer share menu. FinalizeDesignButton has three idle labels driven by DESIGN.md existence + staleness, plus a pending state with a spinner and a cancel link that maps to useFinalizeProject's AbortController. Error toasts are owned by ProjectView so the button doesn't carry its own toast surface. ContinueInCliButton renders disabled with a Finalize-pointing tooltip when DESIGN.md is missing (so the workflow is discoverable rather than hidden), enabled when fresh, and enabled with a stale chip otherwise. Chip text is the spec's canonical "Spec is stale — regenerate?" — N-turns-ago is deferred per spec §4.6. Toast.tsx is a tiny transient component that mirrors PromptTemplatePreviewModal's state-based toast pattern; supports a secondary details line so daemon error envelopes that carry an upstream explanation (e.g. Anthropic account-usage cap) can surface the real reason alongside the daemon's category label. CSS appends one block to apps/web/src/index.css mirroring the existing app-project-title token usage; no CSS modules in this repo (verified by grep). * test(web): cover ContinueInCliButton states + interaction wiring Three rendered states (DESIGN.md missing → disabled with the Finalize-pointing tooltip; DESIGN.md fresh → enabled, no chip; DESIGN.md stale → enabled with the canonical "Spec is stale — regenerate?" chip), plus three onClick branches (no-op when disabled, fires once when fresh, fires once when stale). Click-handler integration with clipboard / shell.openPath / toast lives in ProjectView (the button is presentational and takes the handler in via props), so those are covered by Phase K's wiring + the manual smoke test rather than the per-component test. * feat(web): wire Continue in CLI + Finalize buttons into ProjectView Mounts the new project-actions toolbar between AppChromeHeader and the chat/workspace split, hidden when workspaceFocused so the focus-mode artifact view stays uncluttered. Wires the four hooks (useProjectDetail, useDesignMdState, useFinalizeProject, useTerminalLaunch) to a single shared toast surface. handleFinalize reads the request body from the existing config: AppConfig prop and uses effectiveMaxTokens(config) to match the chat-flow's maxTokens defaulting; on success it refreshes useDesignMdState so the toolbar re-renders with the new chip state. handleContinueInCli builds the literal clipboard prompt, copies it, opens the working directory via shell.openPath on desktop / falls through to a manual-instruction toast on browser, and surfaces shell.openPath failures with a fallback toast that names the path. Errors lift into the same toast surface (a useEffect tied to finalize.error) so the daemon's category message + body.error.details reach the user as the spec's two-line render — covered by hook test 16a in the prior commit. ⌘+Shift+K (mac) / Ctrl+Shift+K (others) is the keyboard accelerator for Continue in CLI; capture-phase, platform-gated, no-op when DESIGN.md is missing. Mirrors the existing FileWorkspace shortcut idiom and does not collide with ⌘+P (Quick Switcher). * fix(web): distinguish timeout abort from user cancel in useFinalizeProject Addresses codex P2 finding on PR #974: the catch block treated every AbortError as a user-initiated cancel and reset to idle silently. If the internal 130 s timeout fired, users saw no failure signal but the daemon's synthesis call may still have been in flight. Adds a timedOutRef set inside the setTimeout callback before controller.abort(), and branches in the catch: timeout → status 'error' with new TIMEOUT code ("Finalize timed out after 130 s. The daemon may still be running."), user cancel → existing idle reset. Reset the ref at the start of every trigger() so a previous timeout doesn't poison the next call. Adds one test using vi.useFakeTimers() that advances past 130_001 ms and asserts the TIMEOUT error surface. * fix(web): surface clipboard failures by rendering the prompt in the toast Addresses codex P2 finding on PR #974: handleContinueInCli ignored copyToClipboard's return value, so when both clipboard paths failed (restricted browser context / insecure origin) the toast still said "paste the prompt" though nothing had been copied — leaving users with no manual-copy recourse in exactly the environments where the fallback should help. handleContinueInCli now branches on copyToClipboard's boolean return. On failure the toast renders the prepared prompt in a scrollable <pre> block and pins itself open (no auto-dismiss) so the user has time to select-and-copy manually. Includes a Dismiss button + the working directory in the secondary details line so the user has the information needed to proceed. The folder-open call is skipped on copy failure because there's nothing to paste yet; the user copies first, then re-clicks Continue in CLI when they're ready. Toast component grows an optional Updating VS Code Server to version 41dd792b5e652393e7787322889ed5fdc58bd75b Removing previous installation... Installing VS Code Server for Linux x64 (41dd792b5e652393e7787322889ed5fdc58bd75b) Downloading: 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 0% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 1% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 2% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 3% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 4% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 5% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 6% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 7% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 8% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 9% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 10% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 11% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 12% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 13% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 14% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 15% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 16% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 17% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 18% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 19% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 20% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 21% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 22% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 23% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 24% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 25% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 26% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 27% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 28% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 29% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 30% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 31% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 32% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 33% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 34% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 35% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 36% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 37% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 38% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 39% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 40% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 41% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 42% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 43% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 44% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 45% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 46% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 47% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 48% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 49% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 50% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 51% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 52% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 53% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 54% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 55% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 56% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 57% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 58% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 59% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 60% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 61% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 62% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 63% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 64% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 65% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 66% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 67% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 68% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 69% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 70% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 71% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 72% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 73% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 74% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 75% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 76% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 77% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 78% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 79% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 80% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 81% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 82% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 83% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 84% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 85% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 86% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 87% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 88% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 89% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 90% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 91% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 92% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 93% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 94% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 95% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 96% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 97% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 98% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99% 99%100%100% Unpacking: 0% 1% 2% 3% 4% 5% 6% 7% 8% 9% 10% 11% 12% 13% 14% 15% 16% 17% 18% 19% 20% 21% 22% 23% 24% 25% 26% 27% 28% 29% 30% 31% 32% 33% 34% 35% 36% 37% 38% 39% 40% 41% 42% 43% 44% 45% 46% 47% 48% 49% 50% 51% 52% 53% 54% 55% 56% 57% 58% 59% 60% 61% 62% 63% 64% 65% 66% 67% 68% 69% 70% 71% 72% 73% 74% 75% 76% 77% 78% 79% 80% 81% 82% 83% 84% 85% 86% 87% 88% 89% 90% 91% 92% 93% 94% 95% 96% 97% 98% 99%100% Unpacked 4009 files and folders to /home/bryan/.vscode-server/bin/41dd792b5e652393e7787322889ed5fdc58bd75b. Looking for compatibility check script at /home/bryan/.vscode-server/bin/41dd792b5e652393e7787322889ed5fdc58bd75b/bin/helpers/check-requirements.sh Running compatibility check script Compatibility check successful (0) prop and the auto-dismiss TTL is suppressed whenever code is present. CSS adds .od-toast-code (monospace, max-height 240 with overflow-auto) and .od-toast-dismiss styling. Six new Toast tests cover details rendering, code rendering, no-auto-dismiss when code is present, auto-dismiss when code is absent, and the Dismiss button affordance. * fix(web): make ContinueInCliButton disabled-state guidance visible Addresses mrcfps's PR #974 review: native <button disabled> does not fire hover/focus events in browsers we ship against, so a `title` tooltip on the disabled button never surfaces. The only guidance for the missing-DESIGN.md state was effectively invisible — defeating the spec's "discoverable, not hidden" intent. Renders the help text as a visible sibling <span> next to the disabled button instead. Adds aria-describedby pointing the button at the hint's id so assistive tech announces the explanation when the disabled button gets focus. The native `disabled` attribute stays so the button still can't be clicked or submitted. CSS adds .project-actions-disabled-hint (muted italic, 11.5px, matches the existing meta/secondary text style on this surface). Test asserts the role="note" hint is in the DOM with the canonical text and that the button's aria-describedby links to its id. * fix(web): keep ProjectActionsToolbar at natural height inside the .app grid The .app container was `grid-template-rows: auto 1fr` — only two rows. Adding ProjectActionsToolbar as a third child between AppChromeHeader and the chat/workspace split made the toolbar the 2nd grid item, so it took the `1fr` row (filling roughly half the viewport) while the split got pushed into an implicit auto row at its content's natural height. Surfaced as a screenshot from Bryan showing the toolbar's background bleeding across most of the screen. Extend grid-template-rows to `auto auto 1fr` and pin the split to `grid-row: 3` explicitly. Now: - Toolbar visible: row 1 = header (auto), row 2 = toolbar (auto), row 3 = split (1fr, fills remaining viewport). - Toolbar hidden via hidden=workspaceFocused → ProjectActionsToolbar returns null, row 2 collapses to 0px (auto with no content), split still fills row 3. No JS changes; existing 609 tests still green. * fix(web): guard useFinalizeProject state writes against superseded triggers Addresses mrcfps's PR #974 P1 review on useFinalizeProject.ts:132 (also called out as P1.3 in lefarcen's deep-dive review). Calling trigger() twice in quick succession aborted the first controller and swapped abortRef to the new one, but the first request's later AbortError catch still unconditionally called setStatus('idle') / setError(null). That cleared the spinner and re-enabled both toolbar buttons while the replacement finalize was still pending — defeating the de-duplication this hook was meant to enforce. Adds an isCurrent() closure (`abortRef.current === controller`) and gates every state-write site after the await: success path, non-OK envelope path, AbortError-timeout, AbortError-cancel, and network-error all bail early when the trigger has been superseded. Per mrcfps: "make every state write request-scoped." Regression test triggers twice in quick succession with a never-resolving fetch, awaits the first promise (it rejects with AbortError), and asserts status stays 'pending' rather than collapsing to 'idle' under the replacement's lifetime. * fix(desktop): allowlist-validate shell.openPath against registered project roots Addresses mrcfps's PR #974 P1 review on runtime.ts:305 (also called out as P1.2 in lefarcen's deep-dive review): the new `shell:open-path` IPC handler accepted any renderer-supplied string and forwarded it straight into Electron's `shell.openPath`, widening the renderer→main trust boundary so XSS or a compromised renderer dependency could open arbitrary local paths to the user. Adds an explicit gate around the bridge: 1. validateExistingDirectory(p) — floor check that rejects empty strings, relative paths, files, apps, and non-existent paths; realpath-resolves so symlink games can't be used to register one path and reach another. 2. createProjectRootGate() — Set-backed allowlist of daemon-validated project working directories. The renderer calls registerProjectRoot(absDir) once per project mount via a new IPC method (preload bridge); the main process only opens paths that pass both the floor check and the allowlist. ProjectView wires the registration via a useEffect tied to projectDetail.resolvedDir, so the active project's daemon-supplied working directory is always the one being approved (not a renderer- synthesized string). Threat-model caveat documented in the runtime.ts comment block: an attacker that fully controls the renderer can also call register with arbitrary paths. Closing that gap fully requires a daemon-side round-trip to derive the canonical resolvedDir from the daemon's project registry, which is deferred to keep this PR focused. Today's allowlist still defends against accidental misuse, bugs, and common XSS payloads that don't know to call register first. Adds apps/packaged/tests/desktop-project-root-gate.test.ts with 13 cases: floor-validation rejection cases (empty / relative / missing / file), happy-path resolution, symlink realpath canonicalization, and the allowlist's register/isApproved/reset semantics. Mirrors the existing apps/packaged/tests/desktop-url-allowlist.test.ts pattern from PR #911 — the packaged workspace hosts the test because apps/desktop has no vitest setup yet. * fix(daemon): wire request-lifecycle abort signal through finalize route Addresses mrcfps's PR #974 P1 review on apps/daemon/src/server.ts:3831-3837 (also called out as P1.1 in lefarcen's deep-dive review): `POST /api/projects/:id/finalize/anthropic` called `finalizeDesignPackage(...)` without threading any request-lifecycle abort, so cancelling the browser fetch only aborted the UI-side request — the daemon's 60–120 s Anthropic call kept running and still wrote DESIGN.md after the UI returned to idle. Adds an AbortController inside the route handler, fired from `res.on('close')`, and threads its signal into the existing `signal?: AbortSignal` parameter on `FinalizeOptions` (finalize-design.ts:70). `callAnthropicWithRetry` already passes the signal through to the underlying fetch, so a client disconnect now propagates all the way to the Anthropic SDK call. Listener-event choice: `res.on('close')` is the canonical event for "client disconnected before response was sent" in Express. The common alternative `req.on('close')` fires whenever the request stream finishes — for POST routes that means as soon as the body-parser middleware drains the body, well before the route does any work. Using req.on('close') would have flipped the abort controller in every successful run; the test caught this empirically. Caveat documented in the route's comment block: an abort fired after the upstream response has been received but before the atomic write completes still allows the write to land. The SDK contract bounds the network round-trip, not the post-network disk handoff. Adds tests/finalize-route-abort.test.ts: spins up the test server, mocks global fetch to capture the daemon-side AbortSignal at the Anthropic call, sends the request via raw http (so we can destroy the underlying socket), waits until the server reaches the Anthropic call, then destroys the socket and asserts that the daemon-side signal received an abort event within 5 s. Three pre-existing project-watchers chokidar tests show flaky timeouts under full-suite concurrency but pass in isolation; unrelated to this fix. * fix(daemon): refactor finalize-route-abort test to satisfy strict TS narrowing The CI typecheck (`pnpm --filter @open-design/daemon typecheck`, which runs both tsconfig.json and tsconfig.tests.json) caught what my pre-push validation missed: TS narrowed `capturedSignal` to literal `null` because vitest's mockImplementation closure can't prove its callback runs, leaving the bare `let capturedSignal: AbortSignal \| null = null` permanently typed at its initial value. At line 184 (`expect(capturedSignal?.aborted).toBe(true)`) the right-hand side of the optional-chain became unreachable, and TS flagged it as `Property 'aborted' does not exist on type 'never'`. Switches to the standard ref-object pattern (`const capture: { signal: AbortSignal \| null } = { signal: null }`). TS narrows let bindings inside closures conservatively but treats object-property writes as opaque, so `capture.signal` reads correctly across the closure boundary. Logic is unchanged. (Pre-push oversight: ran `pnpm --filter @open-design/web typecheck` but not the full repo `pnpm typecheck` after the daemon test landed; the daemon's own typecheck would have caught this. Adding `pnpm typecheck` back into the standard pre-push checklist.) * fix(desktop): make shell.openPath gate daemon-controlled and reject .app bundles Addresses lefarcen + mrcfps PR #974 P1 reviews on the previous path allowlist (commit `8bf56597`): - mrcfps (runtime.ts:45): `validateExistingDirectory` accepted macOS `.app` bundles because they're directories, so the gate would forward `/Applications/Safari.app` (or any other app bundle) into shell.openPath and launch the application — a stronger capability than the bridge's intended "reveal the project folder" feature. - lefarcen (runtime.ts:396): the allowlist was renderer-controlled. A compromised renderer could call `shell:register-project-root` with any existing absolute directory and then `shell:open-path` that same path; the IPC injection issue I'd documented as "deferred" was the central reviewer concern, not an acceptable caveat. Both reviewers asked for the gate to be derived from a daemon-authoritative source. The redesign drops the renderer-controlled register/openPath pair and replaces it with a single `openPath(projectId)` bridge call. The desktop main process resolves the project ID by calling the daemon's `GET /api/projects/:id` endpoint over the web sidecar proxy (which already forwards `/api/` to the daemon — verified in apps/web/sidecar/server.ts:209 and apps/web/next.config.ts:77), parses `resolvedDir` from the response, validates it against the floor (absolute, exists, is-directory, not .app), and only then forwards to `shell.openPath`. The renderer never names the path directly, so a compromised renderer cannot escalate to opening arbitrary local paths — it can only name a project the daemon already knows about, and the canonical path comes from the daemon's own response. Surface changes: - `runtime.ts`: `createProjectRootGate` removed. `fetchResolvedProjectDir(webUrl, projectId, fetchImpl?)` added. `validateExistingDirectory` rejects `.app` suffix after the realpath check (so symlinked launders are caught too). `shell:open-path` handler signature changes from `(path)` to `(projectId)`; `shell:register-project-root` handler removed. - `preload.cts`: `openPath(projectId)`; `registerProjectRoot` removed from the bridge surface. - `apps/web/src/types/electron.d.ts`: type updated to match. - `useTerminalLaunch.ts`: `open(projectId)` instead of `open(dir)`. - `ProjectView.tsx`: passes `project.id` to `terminalLauncher.open`; the registerProjectRoot useEffect is deleted. Toast text still reads `projectDir` (from `useProjectDetail.resolvedDir`) for fallback messages — the display* path is independent of the open mechanism. - `apps/packaged/tests/desktop-project-root-gate.test.ts`: rewritten to cover `validateExistingDirectory` (8 cases including the new `.app` suffix and symlinked-bundle rejection) and `fetchResolvedProjectDir` (8 cases including empty/invalid project ids, daemon HTTP success/failure, missing resolvedDir, network error, and URL canonicalization). Total: 16 passing tests, ~330 LOC churn including test rewrites. Lesson learned (from the iteration loop, not the code): when a reviewer asks for "ideally X, or at least Y," shipping Y with a deferred-X note flags the gap rather than fixing it. Either ship X or argue Y is sufficient; don't middle-ground. * feat(contracts,sidecar-proto): add desktop-auth IPC + fromTrustedPicker Schema-only prep for the PR #974 round-3 fix. Adds the two type extensions the daemon HTTP gate and the desktop main process will build on: - packages/sidecar-proto: SIDECAR_MESSAGES.REGISTER_DESKTOP_AUTH, with a base64-validated `{ secret }` payload + RegisterDesktopAuthResult. Updates normalizeDaemonSidecarMessage to accept the new message and pins both branches (accept + reject) in tests/index.test.ts. - packages/contracts: ProjectMetadata.fromTrustedPicker — a marker the daemon stamps on folder-imported projects whose POST /api/import/folder passed the desktop HMAC gate. The marker is privileged in the same way as `baseDir`: only the gated import handler sets it, and the desktop main process refuses to forward `shell.openPath` for folder-imported projects whose metadata lacks it. * fix(daemon): gate /api/import/folder on desktop HMAC token Closes the renderer→arbitrary-baseDir→shell.openPath bypass chain flagged by lefarcen and mrcfps in round 3 of PR #974. Both reviewers converged on the same gap: the previous round only moved path resolution into the daemon, but renderer JS could still POST /api/import/folder with any absolute path, get a project ID back, and then call openPath(projectId) to reveal the attacker-chosen path. Daemon-side closure: - New module-scope desktop auth secret + setter exported from apps/daemon/src/server.ts. The secret is null at boot (web/standalone mode unaffected) and gets set when the desktop main process registers it over the daemon's sidecar IPC. - New `verifyDesktopImportToken` pure helper. Verifies tokens shaped `${nonce}~${exp}~${signature}` against HMAC-SHA256(secret, baseDir + "\n" + nonce + "\n" + exp). Field separator is `~` (not `.`) because ISO 8601 expiries embed dots; `~` is in neither base64url nor ISO 8601 character sets. Rejects expired tokens, replayed nonces, and expiries beyond 2× the 60s TTL. - New middleware on POST /api/import/folder. When the secret is set, every request must carry a valid `X-OD-Desktop-Import-Token` header bound to the requested baseDir. Rejected requests return 403 with FORBIDDEN. When the secret is unset (no desktop registered), the route is unchanged so web-only deployments and standalone daemons keep working. - Trusted imports get `metadata.fromTrustedPicker: true` stamped on the project. POST /api/projects and PATCH /api/projects/:id reject any client-supplied `fromTrustedPicker` (privileged the same way as `baseDir`), and the PATCH preservation block re-stamps the marker on partial-metadata patches so it cannot be silently stripped. - Daemon sidecar IPC handler: REGISTER_DESKTOP_AUTH calls setDesktopAuthSecret with the base64-decoded secret. The HTTP and IPC servers share a process so the registration takes effect immediately for the next inbound /api/import/folder call. Tests: - apps/daemon/tests/desktop-import-token-gate.test.ts (15 cases): web mode acceptance, no-token rejection, malformed-token rejection, wrong-secret rejection, wrong-baseDir rejection, expired rejection, oversized-window rejection, valid mint + trusted-picker stamp + replay rejection, plus 6 pure-helper cases for verifyDesktopImportToken. afterAll() clears the secret to keep the shared HTTP server clean for sibling test files. - apps/daemon/tests/projects-routes.test.ts (+2 cases): POST and PATCH reject `fromTrustedPicker` in client-supplied metadata. Existing folder-import-route.test.ts continues to pass because none of those tests register a desktop secret; the gate stays dormant. * fix(desktop,web): atomic pickAndImport replacing pickFolder; openPath trusted-picker check Closes the renderer→arbitrary-baseDir bypass at the bridge boundary. The renderer no longer receives a raw filesystem path from the main process; the picker dialog and the import call live in a single main-process transaction. Desktop main: - runDesktopMain generates a per-process 32-byte secret and registers it with the daemon over the daemon's sidecar IPC before the BrowserWindow is created. registerDesktopAuthWithDaemon retries a few times because tools-dev / tools-pack spawn daemon, web, and desktop as siblings, so the daemon may not be listening yet on desktop boot. A failed registration logs a warning and the runtime refuses pickAndImport calls (no secret → no token can be minted). - runtime.ts replaces the `dialog:pick-folder` IPC with `dialog:pick-and-import`. The handler shows the picker, mints an HMAC token bound to the chosen path, POSTs /api/import/folder via the discovered web URL with the token + body, and returns the daemon's ImportFolderResponse to the renderer (or a structured failure envelope). Renderer never sees the path or the token. - shell:open-path now consults a new pure helper `isOpenPathAllowedForProject` that refuses folder-imported projects whose metadata lacks `fromTrustedPicker: true`. This is the literal interpretation of mrcfps's round-3 follow-up: openPath is gated to projects whose resolvedDir came from the trusted-picker flow, not just transitively via the import gate. Native projects (no baseDir → daemon-owned <projectsRoot>/<id>) are always safe to open. - fetchResolvedProjectDir now returns a `ResolvedProjectDirContext` with hasBaseDir + fromTrustedPicker so the openPath handler can enforce the marker check. - New `signDesktopImportToken` pure helper mirrors the daemon-side signer with the same `~`-separated wire shape, exported for the packaged workspace's test file. Preload bridge: - `pickFolder` is deleted. The new `pickAndImport(init?)` returns the daemon's import response or a structured failure. `openPath` keeps its existing signature; its trust gate now lives in the main process. Web renderer: - electron.d.ts drops `pickFolder` and adds `pickAndImport` with the shared DesktopPickAndImportResult union pulled from contracts. - NewProjectPanel: when running on Electron (pickAndImport bridge present), the "Open folder" button calls pickAndImport atomically and forwards the response through a new `onImportFolderResponse` prop. On web (no bridge), the existing manual baseDir input keeps working — browser builds have no shell.openPath surface so a renderer-named path cannot escalate. - EntryView and App.tsx pass through the new callback. App's `handleImportFolderResponse` updates state from the response without a second fetch (the import already happened in the main process). Tests (apps/packaged/tests/desktop-project-root-gate.test.ts): - 3 cases for `isOpenPathAllowedForProject`: native allowed, trusted-picker allowed, legacy folder-import refused. - 6 cases for `signDesktopImportToken`: shape (~-separated), determinism, signature flips when secret/baseDir/nonce/exp changes. - Existing fetchResolvedProjectDir cases extended for the new `context` shape and additional cases that prove the metadata inspection (hasBaseDir, fromTrustedPicker) reads the daemon response correctly. * fix(daemon): make desktop import-folder gate fail-closed (PR #974 round 4) lefarcen P1 on round 3 of PR #974: the gate's `secret == null → accept` branch (originally intended to keep web-only deployments unaffected) let a renderer bypass the import boundary in two real desktop edges: - Startup race: desktop's REGISTER_DESKTOP_AUTH IPC hasn't reached the daemon yet, but the renderer is already alive in the BrowserWindow and races to fetch /api/import/folder directly with arbitrary baseDir. - Daemon restart mid-session: the new daemon process boots tokenless while a desktop is still running. Same shape: renderer fetches the route, daemon falls through to "web mode", accepts the untrusted baseDir. shell.openPath rejects (no fromTrustedPicker marker) but the daemon's other file APIs (read/write project files, list directories) operate on the attacker-chosen path. Two coordinated mechanisms close that: (1) Sticky in-process flag. `desktopAuthEverRegistered` flips to true on first non-null `setDesktopAuthSecret(...)` and never goes back. setDesktopAuthSecret(null) (used by tests) does NOT relax the gate so production code can never silently fall back to fail-open. Add `resetDesktopAuthForTests()` for vitest cleanup. (2) Orchestrator-pinned mode via OD_REQUIRE_DESKTOP_AUTH=1 read at module load. tools-dev / tools-pack / apps/packaged set this when the daemon is spawned in a desktop-bundled flow (separate commits). With the env set, the gate is active from request 0 — a renderer racing /api/import/folder before registration completes gets a 503 DESKTOP_AUTH_PENDING (transient, retry). Standalone-daemon (web-only) deployments where neither mechanism fires keep the gate dormant and the route's behavior unchanged. Also addresses lefarcen P3 (whitespace HMAC mismatch): the desktop signs the exact picker output, so the daemon must verify the same string. The previous version trimmed `baseDir` before HMAC, which would reject legitimate paths whose final component carried edge whitespace. Use the raw request-body baseDir for verification; the existing trim()+realpath() logic still normalizes for fs operations. New error code: `DESKTOP_AUTH_PENDING` (HTTP 503, retryable). Tests: - `stays fail-closed (503 DESKTOP_AUTH_PENDING) after a registered secret is cleared` — exercises the sticky flag. - `verifies the exact request-body baseDir, not a trimmed version` — pins the round-4 P3 fix. - All existing desktop-import-token-gate cases continue to pass; the beforeEach/afterEach/afterAll resetters now use resetDesktopAuthForTests() to honor the sticky flag. * fix(tools-dev,packaged): pin desktop import-auth on daemon spawn PR #974 round-4 P1 follow-through. The daemon-side fail-closed gate needs OD_REQUIRE_DESKTOP_AUTH=1 in the daemon's spawn env whenever the daemon is paired with a desktop, so the gate is active from request 0 and the daemon-restart-mid-session bypass cannot reopen. tools-dev: - spawnDaemonRuntime accepts a `requireDesktopAuth` option that appends OD_REQUIRE_DESKTOP_AUTH=1 to the spawn env. - startDaemon takes the same flag and additionally checks whether a desktop runtime is already alive in this namespace; either branch pins the env (revival case where the daemon died mid-session and the user runs `tools-dev start daemon` to bring it back up). - startApp threads the bundled-target list down so the daemon spawn knows when desktop is queued in the same orchestration even though the daemon starts first. - The `start` / `restart` / `run` command actions pass the resolved target list into startApp. apps/packaged: - Packaged builds always pair a desktop with the daemon, so startPackagedSidecars unconditionally sets OD_REQUIRE_DESKTOP_AUTH=1 in the daemon child env. Headless builds also flow through this same path, so the same gate applies. Standalone-daemon flows unaffected: `tools-dev start daemon` (alone, no desktop running, no desktop in the bundled target list) does not set the env, and the daemon's gate stays dormant — current web-only behavior is preserved. * fix(desktop,web): align project-id regex with daemon; surface pickAndImport failures mrcfps round-4 nits on PR #974. apps/desktop/src/main/runtime.ts (mrcfps #1): the previous client-side regex `^[a-zA-Z0-9_-]+$` rejected `.` even though the daemon's canonical isSafeId / POST /api/projects accept `[A-Za-z0-9._-]{1,128}`. Result: dotted ids like `my-project.v2` were valid backend-side but got "project id contains disallowed characters" before fetchResolvedProjectDir even hit the network, regressing Continue in CLI / Finalize for those projects. Align the regex with the daemon's shape, comment-tag the rationale. apps/packaged/tests/desktop-project-root-gate.test.ts: add a regression case for a dotted id and one for the 128-char length cap (the new regex exposes both, the old regex obscured the dotted one). apps/web/src/components/NewProjectPanel.tsx (mrcfps #2): the `if (!result \|\| result.ok !== true) return` branch swallowed every non-OK pickAndImport shape (`desktop auth secret not registered`, `web sidecar URL not available`, daemon HTTP errors with details) the same way as the explicit `{ canceled: true }` cancel — leaving the user with a silent no-op when the trusted-picker flow couldn't even get off the ground. Reserve silent-return for the cancel case only; surface every other reason via a Toast (existing component, already used by ProjectView for related Continue-in-CLI flows). The new `formatPickAndImportErrorDetails` helper flattens daemon ApiError envelopes into a single readable secondary line so the operator sees both the category ("Open folder failed: daemon returned HTTP 503") and the upstream reason ("desktop auth required but secret not yet registered"). * docs(architecture): document desktop folder-import auth boundary lefarcen P3 on PR #974 round 4: the `Folder import` section in docs/architecture.md still documented only realpath / sandbox / RUNTIME_DATA_DIR checks and omitted the new desktop HMAC trust boundary, replay/TTL behavior, fail-closed semantics, daemon-restart edge, and legacy-import migration note. Without that subsection it's hard to review whether the 60s TTL, the `~`-separated token shape, or the legacy folder-imports needing re-pick are intentional product decisions or overlooked gaps. Add a "Desktop folder-import auth (PR #974)" subsection covering: - The trust handshake (32-byte secret over sidecar IPC at desktop boot). - Token shape (`${nonce}~${exp}~${signature}`), HMAC payload, and why `.` cannot be the field separator (ISO 8601 expiries embed dots). - TTL and replay behavior (60s, single-use, 2× TTL upper bound). - Fail-closed mechanisms — sticky in-process flag and OD_REQUIRE_DESKTOP_AUTH env var pinning. - Web-only deployments are unaffected (browser builds have no shell.openPath surface). - The `metadata.fromTrustedPicker` marker and the openPath-side defense-in-depth check. - Legacy folder-imports need re-pick to use the Continue-in-CLI button. - Daemon-restart edge: 503 DESKTOP_AUTH_PENDING until desktop re-registers; restart desktop to recover. * fix(packaged): skip desktop-auth gate in headless mode (PR #974 round 5 P2) Round 5 (lefarcen P2): packaged headless mode (daemon+web only, no Electron) was inheriting OD_REQUIRE_DESKTOP_AUTH=1 from the round-4 unconditional pin in startPackagedSidecars. Headless never runs desktop main, so no client could ever register an HMAC secret and folder import returned 503 DESKTOP_AUTH_PENDING permanently — even though headless has no shell.openPath surface to exploit. Plumb a required `requireDesktopAuth: boolean` option through startPackagedSidecars: apps/packaged/src/index.ts (Electron entry) passes true; apps/packaged/src/headless.ts passes false. Extract buildPackagedDaemonSpawnEnv as a pure helper so vitest can pin both branches without spawning a child process. Tests added in apps/packaged/tests/sidecars.test.ts cover both branches plus OD_LEGACY_DATA_DIR / daemonCliEntry env forwarding edges. Refs: nexu-io/open-design#974 * fix(desktop,daemon): lazy auth retry + canonical HMAC binding (PR #974 round 5 P1+P3) Round 5 (lefarcen P1, mrcfps): a daemon restart under OD_REQUIRE_DESKTOP_AUTH=1 left desktop holding a stale secret while the new daemon process required a fresh registration — folder import returned 503 DESKTOP_AUTH_PENDING permanently until the user restarted desktop. Same dead-end if the startup handshake missed its retry window. Round 5 (lefarcen P3): the daemon verified the HMAC against raw request-body baseDir, then trimmed before realpath(). A picker selection of "/tmp/foo " could authorize an import of "/tmp/foo" — token bound to a different path than the one imported. Three coordinated fixes: 1. P1 lazy retry: extract pickAndImportFolder as a pure helper that takes injected fetch / mintToken / registerDesktopAuth deps. On 503 DESKTOP_AUTH_PENDING from /api/import/folder, re-invoke the registration callback once, mint a fresh token (new nonce + new exp keeps replay protection), and POST again. Single retry, no infinite loop. Other failure shapes return immediately to the renderer. 2. P1 wiring: runDesktopMain now ALWAYS passes desktopAuthSecret to the runtime regardless of whether the initial handshake succeeded, plus a registerDesktopAuthWithDaemon callback the runtime invokes lazily. Soften the startup warning text to match the new recovery semantics. 3. P3 binding: trim picker output ONCE on the desktop side before both signing the HMAC and POSTing. Daemon-side verification stays against raw request-body baseDir (round-4 behavior); the daemon's defensive trim before realpath() is now a no-op for desktop traffic and only load-bearing for web-mode callers (path.isAbsolute(" /foo ") is false). End-to-end: desktop-signed string == request body == HMAC- verified string == realpath() input. Tests: - apps/packaged/tests/desktop-pick-and-import.test.ts (NEW, 7 cases): lazy-retry happy path; lazy-retry exhausted (re-register WAS called); single-attempt happy path (no unnecessary IPC); optional-callback no-op; non-503 failures bypass retry; network errors; non-PENDING 503 bypasses retry. - apps/daemon/tests/desktop-import-token-gate.test.ts: replace round-4 whitespace test with two round-5 binding tests — the trimmed string flows end-to-end (HMAC verifies, project metadata.baseDir equals realpath of trimmed input), and a request whose body baseDir diverges from the HMAC-bound string is rejected 403. docs/architecture.md §"Desktop folder-import auth" — update the daemon- restart-edge bullet to describe the lazy-retry recovery (round 4 said "restart desktop to recover", which is now wrong) and add a headless- packaged-mode bullet describing the round-5 P2 gate exclusion. Refs: nexu-io/open-design#974 * feat(sidecar-proto,daemon): surface desktopAuthGateActive over STATUS IPC (PR #974 round 6 prep) Round 6 (mrcfps): the split-start dev flow `tools-dev start daemon` -> `tools-dev start desktop` was leaving the daemon ungated because `OD_REQUIRE_DESKTOP_AUTH=1` is only injected when daemon and desktop spawn in the same orchestrator invocation. To fix that, tools-dev needs to introspect the running daemon's gate state before launching desktop main — but the existing STATUS IPC didn't carry the flag. This commit extends `DaemonStatusSnapshot` with a required `desktopAuthGateActive: boolean` and wires the daemon sidecar's STATUS handler (and the public `status()` method on the handle) to recompute the value from `isDesktopAuthGateActive()` per request, since the flag flips after `REGISTER_DESKTOP_AUTH` and stays sticky. Extracted `withCurrentDesktopAuthGate(snapshot)` as a tiny pure helper so the wiring is testable without booting a real IPC server. The new test pins four scenarios: - no secret registered (web-only mode) -> false - after `setDesktopAuthSecret(buf)` -> true - after `setDesktopAuthSecret(null)` (sticky) -> still true - input snapshot's stale value is overridden by the live flag The orchestrator-side consumer lands in the next commit (`tools/dev/src/desktop-auth-gate.ts`). Refs: nexu-io/open-design#974 * fix(tools-dev): auto-restart ungated daemon before desktop start (PR #974 round 6 mrcfps) Round 6 (mrcfps): the split-start dev sequence `tools-dev start daemon` -> `tools-dev start desktop` was leaving the daemon running without `OD_REQUIRE_DESKTOP_AUTH=1`. The env var is only injected when (A) daemon and desktop spawn in the same orchestrator invocation (`startApp` line ~682) or (B) a desktop runtime is already alive at daemon spawn time (`startDaemon` lines ~595-596). Neither fires for the split flow, so a renderer (or any local HTTP client) could `POST /api/import/folder` directly with an arbitrary `baseDir` before the desktop's first registration POST. Round-5's lazy retry didn't help: it triggers on `503 DESKTOP_AUTH_PENDING`, and the ungated daemon returns 200. Close the gap by introspecting the running daemon's `desktopAuthGateActive` (added to the STATUS IPC in the prior commit) at the start of `startApp(DESKTOP, ...)`. When the daemon reports the gate inactive, stop the daemon (and web, if running), respawn the daemon with `requireDesktopAuth: true`, restart web, then proceed with the desktop start. Restart order is critical and pinned by tests: web stops FIRST (so the web->daemon proxy doesn't serve a transient 502 against the down-then-up daemon), then daemon stops, then daemon respawns gated, then web restarts. The bundled-targets path (`pnpm tools-dev`) is unaffected because trigger (A) already armed the gate at first daemon spawn — the helper costs one ~800ms STATUS IPC roundtrip and returns no-op. Helper lives in its own module (`tools/dev/src/desktop-auth-gate.ts`) so the regression test can import it without triggering the `cli.parse()` side effect at the bottom of `tools/dev/src/index.ts`. Five `node:test` cases pin the call sequence — no daemon, gate active, gate inactive + no web, gate inactive + web running, log shape — so a future refactor can't silently regress the gate. Two synthetic `DaemonStatusSnapshot` literals in `inspectAppStatus` and `inspect` (used when the IPC is unreachable) get `desktopAuthGateActive: false` to satisfy the now-required type field — semantically correct since "no daemon answering" trivially means "no gate active." `docs/architecture.md` adds a new bullet under the Desktop folder- import auth section describing this auto-restart behavior. Refs: nexu-io/open-design#974 * fix(daemon): combine finalize request-abort + timeout signals (PR #974 round 7 lefarcen P1) Round 6 wired the route handler to pass `finalizeAbort.signal` into `finalizeDesignPackage`, but the helper only created its own DEFAULT_TIMEOUT_MS controller when no caller signal was supplied. The result: a client that stayed connected could hold the finalize lock and upstream call indefinitely. Always create the timeout controller; when the caller passes a signal, combine both via `AbortSignal.any` so neither cancel path replaces the other. Adds two regression tests in finalize-design.test.ts: - timeout fires when caller signal never aborts - pre-aborted caller signal still cancels Adds an internal `timeoutMs` option to FinalizeOptions so tests can exercise the abort path without a 120 s wait or fake-timer chains. Production callers omit it; default remains DEFAULT_TIMEOUT_MS. * fix(daemon): allow PATCH preserving existing fromTrustedPicker marker (PR #974 round 7 lefarcen P2) The PATCH /api/projects/:id handler was rejecting any metadata that contained `fromTrustedPicker`, including the unchanged `true` marker that the linked-folder UI re-spreads when editing `linkedDirs`. Trusted folder-imported projects could not update other metadata fields without 400-ing on their own marker. Switch the rejection condition from `'in'` to a value comparison: only reject when the incoming value differs from the persisted one (`patch.metadata.fromTrustedPicker !== existingMeta?.fromTrustedPicker`). That keeps acquisition (existing=undefined, patch true) and flip (existing=true, patch false) attempts blocked while letting the UI re-spread the existing marker. POST /api/projects stays strict; that path has no existingMeta. Adds two regression tests in desktop-import-token-gate.test.ts: - allows PATCH preserving the existing fromTrustedPicker:true marker - rejects PATCH that flips fromTrustedPicker on a trusted project * fix(desktop,packaged): main-process api uses daemon URL not webUrl (PR #974 round 7 lefarcen P2) Packaged builds load the renderer from `od://app/` and report that URL through `discoverWebUrl`. But Node-side `globalThis.fetch` (undici) does not route through Electron's registered `od://` protocol handler — that handler runs in the renderer's protocol scope, not in main-process Node. So `pickAndImportFolder` and `fetchResolvedProjectDir` calls from main silently failed in packaged builds against the protocol scheme. Add `discoverDaemonUrl` to `DesktopRuntimeOptions` and `DesktopMainOptions`. The packaged shell already has the sidecar's real `http://127.0.0.1:<port>` URL (`sidecars.daemon.url` from STATUS IPC) — thread it through to the runtime. Main-process API calls now prefer the daemon URL and fall back to the renderer URL for tools-dev (where it is itself http://127.0.0.1). `PickAndImportFolderDeps.webUrl` renamed to `apiBaseUrl` so the boundary is explicit at the type level; `fetchResolvedProjectDir`'s first parameter renamed similarly. tools-dev callers see no behavior change — their web URL is already an http://127.0.0.1 URL Node fetch can hit. Test (`apps/packaged/tests/desktop-pick-and-import.test.ts`): - existing 7 cases updated to the new prop name (no behavior change) - new case pins URL composition: builds `${apiBaseUrl}/api/import/folder` and never produces a custom-protocol URL. Note for review: this test pins URL composition; full Electron protocol handler integration (renderer fetch through `od://`) is not exercised in unit tests here. * fix(tools-dev): preserve daemon/web ports across desktop-auth gate restart (PR #974 round 7 lefarcen P2) Round 6 added the split-start auto-restart in ensureDaemonGateForDesktop to close the dev-flow gap where `start daemon` then `start desktop` left the daemon ungated. The restart was passing the current `start desktop` CLI options to startDaemonGated/startWeb, which meant a stack started with `--daemon-port 17456 --web-port 17573` could be silently moved to random ports during the hardening restart, breaking browsers and scripts pinned to those ports. Extract the running ports from the STATUS snapshots (daemon.url and web.url) and forward them as explicit `{ port }` callback args. The closure in `tools/dev/src/index.ts` overrides the corresponding option when a port was extracted; null falls back to the original CLI flags. Adds three regression tests in tools/dev/tests/desktop-auth-gate.test.ts: - preserves the running daemon port across the hardening restart - preserves the running web port across the hardening restart - falls back to caller options (port:null) when the URL has no port * fix(web): refresh useDesignMdState on file/chat events (PR #974 round 7 mrcfps) useDesignMdState() previously only recomputed on mount and on explicit refresh() (called once after finalize). Once the user kept working — editing files or sending more chat turns — the stale/fresh badge could drift out of sync because file mtimes and conversation updatedAt moved past the recorded generatedAt without the hook re-checking. Hook accepts an optional `refreshKey: number` arg; ProjectView keeps a counter and bumps it on three events: - file-changed SSE (covers tool-emitted file mutations) - live_artifact* SSE (covers chat turns that emit artifacts) - streaming `true → false` edge (covers pure-text chat turns) The hook treats refreshKey as a compute() dep; React's Object.is comparison short-circuits the no-op renders, so each bump is a single recompute pass. Adds a regression test in useDesignMdState.test.tsx: - flips stale state after a refreshKey bump without remounting * fix(web): degraded-state useDesignMdState on malformed provenance (PR #974 round 7 mrcfps) useDesignMdState used to report `{ isStale: false, staleReason: null }` when the parser could not extract a comparison timestamp from the DESIGN.md `## Provenance` section. The pinned test made that the documented behavior. As mrcfps pointed out, that fails open exactly when the freshness signal is most untrustworthy: any provenance- formatting drift silently disables the staleness warning. Extend `DesignMdStaleReason` with a third variant `'unknown-provenance'`. On `generatedMs === null`, return `{ isStale: true, staleReason: 'unknown-provenance' }`. ContinueInCliButton renders a distinct chip text "Spec freshness unknown — regenerate to refresh signal" for that variant; the button stays enabled because not-comparable is not the same as broken state. Tests: - modify the existing pinned test to assert the new degraded state - add an end-to-end useDesignMdState test feeding a malformed Provenance section through compute() so a regression that re-pins fresh-on-null at the hook level (not just computeStale) fails fast - add ContinueInCliButton render + click tests for the new chip --------- Co-authored-by: DevForgeAI CI/CD Engineer <devforge-ai@development.ai> Co-authored-by: lefarcen <935902669@qq.com>		2026-05-10 11:44:32 +08:00
.github	ci: optimize beta release packaging cache (#1095 )	2026-05-10 10:11:05 +08:00
.vaunt	feat: enable Vaunt contributor recognition with 5-tier system (#908 )	2026-05-08 17:44:12 +08:00
apps	feat(web): add Finalize design package + Continue in CLI buttons (#451 ) (#974 )	2026-05-10 11:44:32 +08:00
assets	feat(web): add pet companion with Codex hatch-pet integration (#296 )	2026-05-02 23:45:39 +08:00
craft	refine typography-hierarchy craft docs — clarify edge cases and make lint measurable (#979 )	2026-05-09 08:13:35 +08:00
deploy	docs(deploy): document Colima build swap helper (#967 )	2026-05-09 02:17:22 +08:00
design-systems	feat(design-systems): add hud, loom, trading-terminal with locale coverage (#1069 )	2026-05-09 19:28:19 +08:00
docs	feat(web): add Finalize design package + Continue in CLI buttons (#451 ) (#974 )	2026-05-10 11:44:32 +08:00
e2e	release: Open Design 0.6.0 (#1080 )	2026-05-09 19:58:11 +08:00
nix	feat(nix): Add official flake with home-manager and NixOS support (#402 )	2026-05-09 23:50:16 +08:00
packages	feat(web): add Finalize design package + Continue in CLI buttons (#451 ) (#974 )	2026-05-10 11:44:32 +08:00
prompt-templates	feat(prompt-templates): add Notion-style team dashboard (Live Artifact) (#799 )	2026-05-07 19:42:09 +08:00
scripts	[codex] Add stable nightly promotion gate (#962 )	2026-05-08 21:48:54 +08:00
skills	feat(skills): add release notes one pager + supporting docs (#873 )	2026-05-09 22:10:36 +08:00
specs	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
story	Refactor project name from "Open Claude Design" to "Open Design" (#1 )	2026-04-28 16:03:35 +08:00
templates	add otd-operations-brief live-artifact template (#794 )	2026-05-08 12:53:24 +08:00
tools	feat(web): add Finalize design package + Continue in CLI buttons (#451 ) (#974 )	2026-05-10 11:44:32 +08:00
.dockerignore	Add Docker Compose deployment workflow (#65 )	2026-05-08 11:51:51 +08:00
.gitignore	feat(nix): Add official flake with home-manager and NixOS support (#402 )	2026-05-09 23:50:16 +08:00
.node-version	add support for VP_HOME environment variable in agent resolution (#859 )	2026-05-08 15:14:37 +08:00
AGENTS.md	docs: add repository-wide code review guidelines (#927 )	2026-05-08 19:18:39 +08:00
CHANGELOG.md	release: Open Design 0.6.0 (#1080 )	2026-05-09 19:58:11 +08:00
CLAUDE.md	docs: add git commit co-author policy (#131 )	2026-04-30 15:08:22 +08:00
CONTRIBUTING.de.md	chore: enforce test directory conventions (#496 )	2026-05-05 15:34:22 +08:00
CONTRIBUTING.fr.md	chore: enforce test directory conventions (#496 )	2026-05-05 15:34:22 +08:00
CONTRIBUTING.ja-JP.md	chore: enforce test directory conventions (#496 )	2026-05-05 15:34:22 +08:00
CONTRIBUTING.md	docs: add skills contributing guide (#1035 )	2026-05-09 15:17:45 +08:00
CONTRIBUTING.pt-BR.md	chore: enforce test directory conventions (#496 )	2026-05-05 15:34:22 +08:00
CONTRIBUTING.zh-CN.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
edited_image.png	feat(editorial-collage): introduce Atelier Zero style landing page as… (#366 )	2026-05-04 13:39:58 +08:00
flake.lock	feat(nix): Add official flake with home-manager and NixOS support (#402 )	2026-05-09 23:50:16 +08:00
flake.nix	feat(nix): Add official flake with home-manager and NixOS support (#402 )	2026-05-09 23:50:16 +08:00
LICENSE	Refactor project name from "Open Claude Design" to "Open Design" (#1 )	2026-04-28 16:03:35 +08:00
package.json	release: Open Design 0.6.0 (#1080 )	2026-05-09 19:58:11 +08:00
pnpm-lock.yaml	Harden security scan findings and upgrade dependencies (#806 )	2026-05-08 19:46:34 +08:00
pnpm-workspace.yaml	Refresh desktop integration control plane (#123 )	2026-04-30 14:23:53 +08:00
QUICKSTART.de.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
QUICKSTART.fr.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
QUICKSTART.ja-JP.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
QUICKSTART.md	fix(settings): add install onboarding links for unavailable local CLIs (#985 )	2026-05-09 21:49:44 +08:00
QUICKSTART.pt-BR.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
QUICKSTART.zh-CN.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
QUICKSTART.zh-TW.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
README.ar.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.de.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.es.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.fr.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.ja-JP.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.ko.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.md	feat(nix): Add official flake with home-manager and NixOS support (#402 )	2026-05-09 23:50:16 +08:00
README.pt-BR.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.ru.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.tr.md	docs(readme): refresh contributors wall (#1004 )	2026-05-09 10:24:58 +08:00
README.uk.md	docs(readme): refresh contributors wall (#1004 )	2026-05-09 10:24:58 +08:00
README.zh-CN.md	docs: fix - update prompts path from web to daemon in README files (#756 )	2026-05-09 15:23:23 +08:00
README.zh-TW.md	docs: add Traditional Chinese QUICKSTART and fix Chinese doc links (#753 )	2026-05-09 21:19:08 +08:00
TRANSLATIONS.md	i18n: add full Thai translation (th) (#1018 )	2026-05-09 15:19:47 +08:00
vercel.json	feat: add vercel.json configuration file (#169 )	2026-04-30 22:54:47 +08:00

README.md

Open Design

The open-source alternative to Claude Design. Local-first, web-deployable, BYOK at every layer — 16 coding-agent CLIs auto-detected on your PATH (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) become the design engine, driven by 31 composable Skills and 72 brand-grade Design Systems. No CLI? An OpenAI-compatible BYOK proxy is the same loop minus the spawn.

English · Español · Português (Brasil) · Deutsch · Français · 简体中文 · 繁體中文 · 한국어 · 日本語 · العربية · Русский · Українська · Türkçe

Why this exists

Anthropic's Claude Design (released 2026-04-17, Opus 4.7) showed what happens when an LLM stops writing prose and starts shipping design artifacts. It went viral — and stayed closed-source, paid-only, cloud-only, locked to Anthropic's model and Anthropic's skills. There is no checkout, no self-host, no Vercel deploy, no swap-in-your-own-agent.

Open Design (OD) is the open-source alternative. Same loop, same artifact-first mental model, none of the lock-in. We don't ship an agent — the strongest coding agents already live on your laptop. We wire them into a skill-driven design workflow that runs locally with pnpm tools-dev, can deploy the web layer to Vercel, and stays BYOK at every layer.

Type make me a magazine-style pitch deck for our seed round. The interactive question form pops up before the model improvises a single pixel. The agent picks one of five curated visual directions. A live TodoWrite plan streams into the UI. The daemon builds a real on-disk project folder with a seed template, layout library, and self-check checklist. The agent reads them — pre-flight enforced — runs a five-dimensional critique against its own output, and emits a single <artifact> that renders in a sandboxed iframe seconds later.

That's not "AI tries to design something". That's an AI that has been trained, by the prompt stack, to behave like a senior designer with a working filesystem, a deterministic palette library, and a checklist culture — exactly the bar Claude Design set, but open and yours.

OD stands on four open-source shoulders:

alchaincyf/huashu-design — the design-philosophy compass. Junior-Designer workflow, the 5-step brand-asset protocol, the anti-AI-slop checklist, the 5-dimensional self-critique, and the "5 schools × 20 design philosophies" idea behind our direction picker — all distilled into apps/daemon/src/prompts/discovery.ts.
op7418/guizang-ppt-skill — the deck mode. Bundled verbatim under skills/guizang-ppt/ with original LICENSE preserved; magazine-style layouts, WebGL hero, P0/P1/P2 checklists.
OpenCoworkAI/open-codesign — the UX north star and our closest peer. The first open-source Claude-Design alternative. We borrow its streaming-artifact loop, its sandboxed-iframe preview pattern (vendored React 18 + Babel), its live agent panel (todos + tool calls + interruptible generation), and its five-format export list (HTML / PDF / PPTX / ZIP / Markdown). We deliberately diverge on form factor — they are a desktop Electron app bundling pi-ai; we are a web app + local daemon that delegates to your existing CLI.
multica-ai/multica — the daemon-and-runtime architecture. PATH-scan agent detection, the local daemon as the only privileged process, the agent-as-teammate worldview.

At a glance

	What you get
Coding-agent CLIs (16)	Claude Code · Codex CLI · Devin for Terminal · Cursor Agent · Gemini CLI · OpenCode · Qwen Code · Qoder CLI · GitHub Copilot CLI · Hermes (ACP) · Kimi CLI (ACP) · Pi (RPC) · Kiro CLI (ACP) · Kilo (ACP) · Mistral Vibe CLI (ACP) · DeepSeek TUI — auto-detected on `PATH`, swap with one click
BYOK fallback	Protocol-specific API proxy at `/api/proxy/{anthropic,openai,azure,google}/stream` — paste `baseUrl` + `apiKey` + `model`, choose Anthropic / OpenAI / Azure OpenAI / Google Gemini, and the daemon normalizes SSE back to the same chat stream. Internal-IP/SSRF blocked at the daemon edge.
Design systems built-in	129 — 2 hand-authored starters + 70 product systems (Linear, Stripe, Vercel, Airbnb, Tesla, Notion, Anthropic, Apple, Cursor, Supabase, Figma, Xiaohongshu, …) from `awesome-design-md`, plus 57 design skills from `awesome-design-skills` added directly under `design-systems/`
Skills built-in	31 — 27 in `prototype` mode (web-prototype, saas-landing, dashboard, mobile-app, gamified-app, social-carousel, magazine-poster, dating-web, sprite-animation, motion-frames, critique, tweaks, wireframe-sketch, pm-spec, eng-runbook, finance-report, hr-onboarding, invoice, kanban-board, team-okrs, …) + 4 in `deck` mode (`guizang-ppt` · `simple-deck` · `replit-deck` · `weekly-update`). Grouped in the picker by `scenario`: design / marketing / operation / engineering / product / finance / hr / sale / personal.
Media generation	Image · video · audio surfaces ship alongside the design loop. gpt-image-2 (Azure / OpenAI) for posters, avatars, infographics, illustrated maps · Seedance 2.0 (ByteDance) for cinematic 15s text-to-video and image-to-video · HyperFrames (heygen-com/hyperframes) for HTML→MP4 motion graphics (product reveals, kinetic typography, data charts, social overlays, logo outros). 93 ready-to-replicate prompts gallery — 43 gpt-image-2 + 39 Seedance + 11 HyperFrames — under `prompt-templates/`, with preview thumbnails and source attribution. Same chat surface as code; outputs a real `.mp4` / `.png` chip into the project workspace.
Visual directions	5 curated schools (Editorial Monocle · Modern Minimal · Warm Soft · Tech Utility · Brutalist Experimental) — each ships a deterministic OKLch palette + font stack (`apps/daemon/src/prompts/directions.ts`)
Device frames	iPhone 15 Pro · Pixel · iPad Pro · MacBook · Browser Chrome — pixel-accurate, shared across skills under `assets/frames/`
Agent runtime	Local daemon spawns the CLI in your project folder — agent gets real `Read`, `Write`, `Bash`, `WebFetch` against a real on-disk environment, with Windows `ENAMETOOLONG` fallbacks (stdin / prompt-file) on every adapter
Imports	Drop a Claude Design export ZIP onto the welcome dialog — `POST /api/import/claude-design` parses it into a real project so your agent can keep editing where Anthropic left off
Persistence	SQLite at `.od/app.sqlite`: projects · conversations · messages · tabs · saved templates. Reopen tomorrow, todo card and open files are exactly where you left them.
Lifecycle	One entry point: `pnpm tools-dev` (start / stop / run / status / logs / inspect / check) — boots daemon + web (+ desktop) under typed sidecar stamps
Desktop	Optional Electron shell with sandboxed renderer + sidecar IPC (STATUS / EVAL / SCREENSHOT / CONSOLE / CLICK / SHUTDOWN) — drives `tools-dev inspect desktop screenshot` for E2E
Deployable to	Local (`pnpm tools-dev`) · Vercel web layer · packaged Electron desktop app for macOS (Apple Silicon) and Windows (x64) — download from open-design.ai or the latest release
License	Apache-2.0

Demo

_{Entry view — pick a skill, pick a design system, type the brief. The same surface for prototypes, decks, mobile apps, dashboards, and editorial pages.}	_{Turn-1 discovery form — before the model writes a pixel, OD locks the brief: surface, audience, tone, brand context, scale. 30 seconds of radios beats 30 minutes of redirects.}
_{Direction picker — when the user has no brand, the agent emits a second form with 5 curated directions (Monocle / Modern Minimal / Tech Utility / Brutalist / Soft Warm). One radio click → a deterministic palette + font stack, no model freestyle.}	_{Live todo progress — the agent's plan streams as a live card. in_progress → completed updates land in real time. The user can redirect cheaply, mid-flight.}
_{Sandboxed preview — every <artifact> renders in a clean srcdoc iframe. Editable in place via the file workspace; downloadable as HTML, PDF, ZIP.}	_{72-system library — every product system shows its 4-color signature. Click for the full DESIGN.md, swatch grid, and live showcase.}
_{Deck mode (guizang-ppt) — the bundled guizang-ppt-skill drops in unchanged. Magazine layouts, WebGL hero backgrounds, single-file HTML output, PDF export.}	_{Mobile prototype — pixel-accurate iPhone 15 Pro chrome (Dynamic Island, status bar SVGs, home indicator). Multi-screen prototypes use the shared /frames/ assets so the agent never re-draws a phone.}

Skills

31 skills ship in the box. Each is a folder under skills/ following the Claude Code SKILL.md convention with an extended od: frontmatter that the daemon parses verbatim — mode, platform, scenario, preview.type, design_system.requires, default_for, featured, fidelity, speaker_notes, animations, example_prompt (apps/daemon/src/skills.ts).

Two top-level modes carry the catalog: prototype (27 skills — anything that renders as a single-page artifact, from a magazine landing to a phone screen to a PM spec doc) and deck (4 skills — horizontal-swipe presentations with deck-framework chrome). The scenario field is what the picker groups them by: design · marketing · operation · engineering · product · finance · hr · sale · personal.

Showcase examples

The visually distinctive skills you'll most likely run first. Each ships a real example.html you can open straight from the repo to see exactly what the agent will produce — no auth, no setup.

_{dating-web · prototype Consumer dating / matchmaking dashboard — left rail nav, ticker bar, KPIs, 30-day mutual-matches chart, editorial typography.}	_{digital-eguide · template Two-spread digital e-guide — cover (title, author, TOC teaser) + lesson spread with pull-quote and step list. Creator / lifestyle tone.}
_{email-marketing · prototype Brand product-launch HTML email — masthead, hero image, headline lockup, CTA, specs grid. Centered single-column, table-fallback safe.}	_{gamified-app · prototype Three-frame gamified mobile-app prototype on a dark showcase stage — cover, today's quests with XP ribbons + level bar, quest detail.}
_{mobile-onboarding · prototype Three-frame mobile onboarding flow — splash, value-prop, sign-in. Status bar, swipe dots, primary CTA.}	_{motion-frames · prototype Single-frame motion-design hero with looping CSS animations — rotating type ring, animated globe, ticking timer. Hand-off ready for HyperFrames.}
_{social-carousel · prototype Three-card 1080×1080 social-media carousel — cinematic panels with display headlines that connect across the series, brand mark, loop affordance.}	_{sprite-animation · prototype Pixel / 8-bit animated explainer slide — full-bleed cream stage, animated pixel mascot, kinetic Japanese display type, looping CSS keyframes.}

Design & marketing surfaces (prototype mode)

Skill	Platform	Scenario	What it produces
`web-prototype`	desktop	design	Single-page HTML — landings, marketing, hero pages (default for prototype)
`saas-landing`	desktop	marketing	Hero / features / pricing / CTA marketing layout
`dashboard`	desktop	operation	Admin / analytics with sidebar + dense data layout
`pricing-page`	desktop	sale	Standalone pricing + comparison tables
`docs-page`	desktop	engineering	3-column documentation layout
`blog-post`	desktop	marketing	Editorial long-form
`mobile-app`	mobile	design	iPhone 15 Pro / Pixel framed app screen(s)
`mobile-onboarding`	mobile	design	Multi-screen mobile onboarding flow (splash · value-prop · sign-in)
`gamified-app`	mobile	personal	Three-frame gamified mobile-app prototype
`email-marketing`	desktop	marketing	Brand product-launch HTML email (table-fallback safe)
`social-carousel`	desktop	marketing	3-card 1080×1080 social carousel
`magazine-poster`	desktop	marketing	Single-page magazine-style poster
`motion-frames`	desktop	marketing	Motion-design hero with looping CSS animations
`sprite-animation`	desktop	marketing	Pixel / 8-bit animated explainer slide
`dating-web`	desktop	personal	Consumer dating dashboard mockup
`digital-eguide`	desktop	marketing	Two-spread digital e-guide (cover + lesson)
`wireframe-sketch`	desktop	design	Hand-drawn ideation sketch — for the "show something visible early" pass
`critique`	desktop	design	Five-dimensional self-critique scoresheet (Philosophy · Hierarchy · Detail · Function · Innovation)
`tweaks`	desktop	design	AI-emitted tweaks panel — the model surfaces the parameters worth nudging

Deck surfaces (deck mode)

Skill	Default for	What it produces
`guizang-ppt`	default for deck	Magazine-style web PPT — bundled verbatim from op7418/guizang-ppt-skill, original LICENSE preserved
`simple-deck`	—	Minimal horizontal-swipe deck
`replit-deck`	—	Product-walkthrough deck (Replit-style)
`weekly-update`	—	Team weekly cadence as a swipe deck (progress · blockers · next)

Office & operations surfaces (prototype mode, document-flavored scenarios)

Skill	Scenario	What it produces
`pm-spec`	product	PM specification doc with TOC + decision log
`team-okrs`	product	OKR scoresheet
`meeting-notes`	operation	Meeting decision log
`kanban-board`	operation	Board snapshot
`eng-runbook`	engineering	Incident runbook
`finance-report`	finance	Exec finance summary
`invoice`	finance	Single-page invoice
`hr-onboarding`	hr	Role onboarding plan

Adding a skill takes one folder. Read docs/skills-protocol.md for the extended frontmatter, fork an existing skill, restart the daemon, it appears in the picker. The catalog endpoint is GET /api/skills; per-skill seed assembly (template + side-file references) lives at GET /api/skills/:id/example.

Six load-bearing ideas

1 · We don't ship an agent. Yours is good enough.

The daemon scans your PATH for claude, codex, devin, cursor-agent, gemini, opencode, qwen, qodercli, copilot, hermes, kimi, pi, kiro-cli, kilo, vibe-acp, and deepseek on startup. Whichever ones it finds become candidate design engines — driven over stdio with one adapter per CLI, swappable from the model picker. Inspired by multica and cc-switch. No CLI installed? The API mode is the same pipeline minus the spawn — choose Anthropic, OpenAI-compatible, Azure OpenAI, or Google Gemini and the daemon forwards normalized SSE chunks back. Loopback is allowed for local LLM providers such as Ollama and LM Studio; non-loopback private, link-local, CGNAT, multicast, reserved, and redirect targets are rejected at the daemon edge.

2 · Skills are files, not plugins.

Following Claude Code's SKILL.md convention, each skill is SKILL.md + assets/ + references/. Drop a folder into skills/, restart the daemon, it appears in the picker. The bundled magazine-web-ppt is op7418/guizang-ppt-skill committed verbatim — original license preserved, attribution preserved.

3 · Design Systems are portable Markdown, not theme JSON.

The 9-section DESIGN.md schema from VoltAgent/awesome-design-md — color, typography, spacing, layout, components, motion, voice, brand, anti-patterns. Every artifact reads from the active system. Switch system → next render uses the new tokens. The dropdown ships with Linear, Stripe, Vercel, Airbnb, Tesla, Notion, Apple, Anthropic, Cursor, Supabase, Figma, Resend, Raycast, Lovable, Cohere, Mistral, ElevenLabs, X.AI, Spotify, Webflow, Sanity, PostHog, Sentry, MongoDB, ClickHouse, Cal, Replicate, Clay, Composio, Xiaohongshu… — plus 57 design skills sourced from awesome-design-skills.

4 · The interactive question form prevents 80% of redirects.

OD's prompt stack hard-codes a RULE 1: every fresh design brief begins with a <question-form id="discovery"> instead of code. Surface · audience · tone · brand context · scale · constraints. A long brief still leaves design decisions open — visual tone, color stance, scale — exactly the things the form locks down in 30 seconds. The cost of a wrong direction is one chat round, not one finished deck.

This is the Junior-Designer mode distilled from huashu-design: batch the questions up front, show something visible early (even a wireframe with grey blocks), let the user redirect cheaply. Combined with the brand-asset protocol (locate · download · grep hex · write brand-spec.md · vocalise), it's the single biggest reason output stops feeling like AI freestyle and starts feeling like a designer who paid attention before painting.

5 · The daemon makes the agent feel like it's on your laptop, because it is.

The daemon spawns the CLI with cwd set to the project's artifact folder under .od/projects/<id>/. The agent gets Read, Write, Bash, WebFetch — real tools against a real filesystem. It can Read the skill's assets/template.html, grep your CSS for hex values, write a brand-spec.md, drop generated images, and produce .pptx / .zip / .pdf files that show up in the file workspace as download chips when the turn ends. Sessions, conversations, messages, tabs persist in a local SQLite DB — pop the project open tomorrow and the agent's todo card is right where you left it.

6 · The prompt stack is the product.

What you compose at send time isn't "system + user". It's:

DISCOVERY directives  (turn-1 form, turn-2 brand branch, TodoWrite, 5-dim critique)
  + identity charter   (OFFICIAL_DESIGNER_PROMPT, anti-AI-slop, junior-pass)
  + active DESIGN.md   (72 systems available)
  + active SKILL.md    (31 skills available)
  + project metadata   (kind, fidelity, speakerNotes, animations, inspiration ids)
  + skill side files   (auto-injected pre-flight: read assets/template.html + references/*.md)
  + (deck kind, no skill seed) DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)

Every layer is composable. Every layer is a file you can edit. Read apps/daemon/src/prompts/system.ts and apps/daemon/src/prompts/discovery.ts to see the actual contract.

Architecture

┌────────────────────── browser (Next.js 16) ──────────────────────┐
│  chat · file workspace · iframe preview · settings · imports     │
└──────────────┬───────────────────────────────────┬───────────────┘
               │ /api/* (rewritten in dev)          │
               ▼                                    ▼
   ┌──────────────────────────────────┐   /api/proxy/{provider}/stream (SSE)
   │  Local daemon (Express + SQLite) │   ─→ any OpenAI-compat
   │                                  │       endpoint (BYOK)
   │  /api/agents          /api/skills│       w/ SSRF blocking
   │  /api/design-systems  /api/projects/…
   │  /api/chat (SSE)      /api/proxy/{provider}/stream (SSE)
   │  /api/templates       /api/import/claude-design
   │  /api/artifacts/save  /api/artifacts/lint
   │  /api/upload          /api/projects/:id/files…
   │  /artifacts (static)  /frames (static)
   │
   │  optional: sidecar IPC at /tmp/open-design/ipc/<ns>/<app>.sock
   │  (STATUS · EVAL · SCREENSHOT · CONSOLE · CLICK · SHUTDOWN)
   └─────────┬────────────────────────┘
             │ spawn(cli, [...], { cwd: .od/projects/<id> })
             ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │  claude · codex · devin (ACP) · gemini · opencode · cursor-agent │
   │  qwen · qoder · copilot · hermes (ACP) · kimi (ACP) · pi (RPC) · kiro (ACP) · kilo (ACP) · vibe (ACP) · deepseek  │
   │  reads SKILL.md + DESIGN.md, writes artifacts to disk            │
   └──────────────────────────────────────────────────────────────────┘

Layer	Stack
Frontend	Next.js 16 App Router + React 18 + TypeScript, Vercel-deployable
Daemon	Node 24 · Express · SSE streaming · `better-sqlite3`; tables: `projects` · `conversations` · `messages` · `tabs` · `templates`
Agent transport	`child_process.spawn`; typed-event parsers for `claude-stream-json` (Claude Code), `qoder-stream-json` (Qoder CLI), `copilot-stream-json` (Copilot), `json-event-stream` per-CLI parsers (Codex / Gemini / OpenCode / Cursor Agent), `acp-json-rpc` (Devin / Hermes / Kimi / Kiro / Kilo / Mistral Vibe via Agent Client Protocol), `pi-rpc` (Pi via stdio JSON-RPC), `plain` (Qwen Code / DeepSeek TUI)
BYOK proxy	`POST /api/proxy/{anthropic,openai,azure,google}/stream` → provider-specific upstream APIs, normalized `delta/end/error` SSE; allows loopback local LLM providers, rejects non-loopback private/link-local/CGNAT/multicast/reserved hosts, and disables upstream redirects at the daemon edge
Storage	Plain files in `.od/projects/<id>/` + SQLite at `.od/app.sqlite` + credentials at `.od/media-config.json` (gitignored, auto-created). `OD_DATA_DIR=<dir>` relocates all daemon data (used for test isolation and read-only-install setups); `OD_MEDIA_CONFIG_DIR=<dir>` further narrows the override to just `media-config.json` for setups that want to keep API keys outside the data dir
Preview	Sandboxed iframe via `srcdoc` + per-skill `<artifact>` parser (`apps/web/src/artifacts/parser.ts`)
Export	HTML (inline assets) · PDF (browser print, deck-aware) · PPTX (agent-driven via skill) · ZIP (archiver) · Markdown
Lifecycle	`pnpm tools-dev start \| stop \| run \| status \| logs \| inspect \| check`; ports via `--daemon-port` / `--web-port`, namespaces via `--namespace`
Desktop (optional)	Electron shell — discovers the web URL through sidecar IPC, no port guessing; same `STATUS`/`EVAL`/`SCREENSHOT`/`CONSOLE`/`CLICK`/`SHUTDOWN` channel powers `tools-dev inspect desktop …` for E2E

Quickstart

Download the desktop app (no build required)

The fastest way to try Open Design is the prebuilt desktop app — no Node, no pnpm, no clone:

open-design.ai — official download page
GitHub releases

Run with Docker

Run Open Design without installing Node.js or pnpm locally.

Requirements

Docker Desktop
Docker Compose v2

Verify Docker:

docker compose version

Start Open Design

git clone https://github.com/nexu-io/open-design.git
cd open-design/deploy
docker compose up -d

Open in your browser:

http://localhost:7456

Common Commands

# View logs
docker compose logs -f

# Restart containers
docker compose restart

# Stop containers
docker compose down

# Pull latest image
docker compose pull
docker compose up -d

For advanced Docker configuration and environment variables, see QUICKSTART.md.

Run from source

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable
corepack pnpm --version   # should print 10.33.2
pnpm install
pnpm tools-dev run web
# open the web URL printed by tools-dev

Environment requirements: Node ~24 and pnpm 10.33.x. nvm/fnm are optional helpers only; if you use one, run nvm install 24 && nvm use 24 or fnm install 24 && fnm use 24 before pnpm install.

For desktop/background startup, fixed-port restarts, and media generation dispatcher checks (OD_BIN, OD_DAEMON_URL, apps/daemon/dist/cli.js), see QUICKSTART.md.

The first load:

Detects which agent CLIs you have on PATH and picks one automatically.
Loads 31 skills + 72 design systems.
Pops the welcome dialog so you can paste an Anthropic key (only needed for the BYOK fallback path).
Auto-creates ./.od/ — the local runtime folder for the SQLite project DB, per-project artifacts, and saved renders. There is no od init step; the daemon mkdirs everything it needs on boot.

Type a prompt, hit Send, watch the question form arrive, fill it, watch the todo card stream, watch the artifact render. Click Save to disk or download as a project ZIP.

First-run state (`./.od/`)

The daemon owns one hidden folder at the repo root. Everything in it is gitignored and machine-local — never commit it.

.od/
├── app.sqlite                 ← projects · conversations · messages · open tabs
├── artifacts/                 ← one-off "Save to disk" renders (timestamped)
└── projects/<id>/             ← per-project working dir, also the agent's cwd

Want to…	Do this
Inspect what's in there	`ls -la .od && sqlite3 .od/app.sqlite '.tables'`
Reset to a clean slate	`pnpm tools-dev stop`, `rm -rf .od`, run `pnpm tools-dev run web` again
Move it elsewhere	`OD_DATA_DIR=<absolute-or-relative-path> pnpm tools-dev run web` — the daemon resolves `~/` and anchors relative paths to the repo root. `OD_MEDIA_CONFIG_DIR=<dir>` narrows the override to just `media-config.json` if you want credentials in a separate location.

Migrating a pre-desktop-app `.od/` into the installed Desktop app

If you ran the repo first and only later installed the packaged Desktop app, the two writers point at different roots:

Repo dev-server (pnpm tools-dev start web) writes to <repo-root>/.od/.

Installed Desktop app writes under <appData>/Open Design/namespaces/<channel>/data/, where <appData> is Electron's per-OS app-data base (everything before the Open Design segment that app.getPath("userData") already includes). The channel suffix is platform-specific — the release workflows append -win/-linux:

Platform	`<appData>` (Electron `appData` base)	Stable channel	Beta channel
macOS	`~/Library/Application Support`	`release-stable`	`release-beta`
Windows	`%APPDATA%` (= `%USERPROFILE%\AppData\Roaming`)	`release-stable-win`	`release-beta-win`
Linux	`$XDG_CONFIG_HOME` (default `~/.config`)	`release-stable-linux`	`release-beta-linux`

Example resolved paths:

macOS beta: ~/Library/Application Support/Open Design/namespaces/release-beta/data/
Windows beta: %APPDATA%\Open Design\namespaces\release-beta-win\data\
Linux beta: ~/.config/Open Design/namespaces/release-beta-linux/data/

If unsure, inspect the packaged daemon log right after the app boots; it logs the resolved daemonDataRoot.

⚠️ Do this in a clean state. Migration replaces (not merges) the Desktop app's data dir with your repo .od/. Both writers must be fully stopped before copying — quit the Desktop app and stop the repo dev-server. SQLite-WAL needs to flush cleanly on both sides; if either daemon is still running it can write SQLite/WAL pages or project/artifact files mid-snapshot, leaving the staged copy inconsistent. If the Desktop app already has projects you care about, decide which side is authoritative before continuing — the steps below back up the Desktop's current data/ to a sibling but do not merge.

Option A: one-shot auto-migration via `OD_LEGACY_DATA_DIR`

Use this when the Desktop app's data/ is still empty, which is the typical state right after the upgrade that surfaced #710. Quit the Desktop app first (so its daemon is not holding app.sqlite), then re-launch with OD_LEGACY_DATA_DIR pointed at your old repo .od/. The daemon stages your payload into a sibling tmp directory and only promotes it into data/ on success; on any failure the staging directory is removed so the next boot retries cleanly.

The daemon refuses, with a visible startup error, when:

the path in OD_LEGACY_DATA_DIR does not contain app.sqlite (typo, deleted source, wrong path), or
the Desktop's data/ already contains any of app.sqlite, projects/, artifacts/, media-config.json, etc. SQLite/WAL pairs and project trees cannot be safely interleaved, so the daemon refuses to merge instead of silently corrupting either side. If the Desktop has already booted and seeded its own data/, use Option B and decide explicitly which side wins.

A .migrated-from marker is written on success so subsequent boots no-op.

Quit the Desktop app first, then re-launch with this env set. The launcher must put the variable into the app process environment, not just the shell that runs open / xdg-open.

macOS (LaunchServices does not inherit shell env, so use the direct binary):

OD_LEGACY_DATA_DIR="/path/to/old/repo/.od" \
  "/Applications/Open Design.app/Contents/MacOS/Open Design"

If you prefer the Dock launcher, set the variable in launchctl first, open the app, then unset it:

launchctl setenv OD_LEGACY_DATA_DIR "/path/to/old/repo/.od"
open "/Applications/Open Design.app"
# After the migration log line appears:
launchctl unsetenv OD_LEGACY_DATA_DIR

Linux (run the binary directly so the env var actually reaches it):

OD_LEGACY_DATA_DIR="/path/to/old/repo/.od" /path/to/open-design
# (e.g. the AppImage you launched, or the unpacked binary under /opt)

Windows (PowerShell):

$env:OD_LEGACY_DATA_DIR="C:\path\to\old\repo\.od"
& "$env:LOCALAPPDATA\Programs\Open Design\Open Design.exe"

The daemon log records [od-migrate] migration complete: copied N entries (...). After the first launch you can clear the env variable; the marker prevents re-migration even on subsequent runs.

Option B: manual copy

To carry your existing projects, SQLite, artifacts, and media-config.json over to the Desktop app, when Option A is not viable (Desktop already has its own data and you want to replace it explicitly).

macOS / Linux (bash):

set -euo pipefail
# 1. Stop both writers so the source and target are quiescent.
#    - Quit the Desktop app (Cmd+Q on macOS, File → Exit on Linux).
#    - Stop the repo dev-server: `pnpm tools-dev stop` from the repo root.
# 2. Set REPO and APP_DATA to your actual paths; the example below is macOS + beta.
REPO="/path/to/open-design"
APP_DATA="$HOME/Library/Application Support/Open Design/namespaces/release-beta/data"

# 3. Preflight: see what (if anything) the Desktop app already has.
ls "$APP_DATA/projects" 2>/dev/null && echo "Desktop already has projects, confirm this is a replace, not a merge."

# 4. Stage into a sibling first, then atomically swap into place. `set -e` plus
#    the explicit rsync exit check guarantee a non-zero copy aborts before any
#    `mv` runs, so the Desktop data dir cannot end up half-populated.
STAGE="${APP_DATA}.staged-$(date +%F-%H%M)"
mkdir -p "$STAGE"
rsync -a --exclude='backup-*' "$REPO/.od/" "$STAGE/" || { echo "rsync failed, aborting before swap"; exit 1; }

# 5. Backup the Desktop's current data, then promote the staged copy.
mv "$APP_DATA" "${APP_DATA}.fresh-baseline-$(date +%F-%H%M)"
mv "$STAGE" "$APP_DATA"

# 6. Relaunch the Desktop app. The daemon applies forward schema changes on boot.

Windows (PowerShell):

$ErrorActionPreference = 'Stop'
# 1. Stop both writers so the source and target are quiescent.
#    - Quit the Desktop app (File > Exit).
#    - Stop the repo dev-server: `pnpm tools-dev stop` from the repo root.
# 2. Set $Repo and $AppData to your actual paths; the example below is stable channel.
$Repo    = 'C:\path\to\open-design'
$AppData = Join-Path $env:APPDATA 'Open Design\namespaces\release-stable-win\data'

# 3. Preflight: see what (if anything) the Desktop app already has.
if (Test-Path (Join-Path $AppData 'projects')) {
  Write-Host 'Desktop already has projects, confirm this is a replace, not a merge.'
}

# 4. Stage into a sibling first. Robocopy /MIR mirrors source to staging, and
#    its exit codes >= 8 are real errors (0..7 are success/info), so we guard
#    explicitly before promoting.
$Stamp = Get-Date -Format 'yyyy-MM-dd-HHmm'
$Stage = "$AppData.staged-$Stamp"
robocopy "$Repo\.od" $Stage /MIR /XD 'backup-*' | Out-Null
if ($LASTEXITCODE -ge 8) { throw "robocopy failed (exit $LASTEXITCODE), aborting before swap" }

# 5. Backup the Desktop's current data, then promote the staged copy.
if (Test-Path $AppData) { Rename-Item $AppData "$AppData.fresh-baseline-$Stamp" }
Rename-Item $Stage $AppData

# 6. Relaunch the Desktop app. The daemon applies forward schema changes on boot.

If anything looks wrong after relaunch, restore the original Desktop data by deleting $APP_DATA (or $AppData on Windows) and renaming the .fresh-baseline-* directory back into place.

⚠️ Schema migrations are forward-only. The daemon applies CREATE TABLE IF NOT EXISTS / ALTER TABLE changes on boot; there is no version guard. After migrating, do not open the same data dir with an older repo checkout — unsupported columns or behavior mismatches can leave the workspace inconsistent. Back up app.sqlite* before the first launch with the new app.

⚠️ Advanced: sharing one data dir between repo dev-server and Desktop app. Pointing both at the same dir via OD_DATA_DIR is possible but only safe one-at-a-time. The daemon opens app.sqlite in WAL mode and writes uncoordinated files under projects/ and artifacts/; running both writers concurrently can corrupt SQLite or clobber artifacts. Always stop the Desktop app before starting the dev-server, and stop the dev-server before opening the Desktop app:
OD_DATA_DIR="$HOME/Library/Application Support/Open Design/namespaces/release-beta/data" \
  pnpm tools-dev start web

Full file map, scripts, and troubleshooting → QUICKSTART.md.

Running the Project

Open Design can run as a web app in your browser or as an Electron desktop application. Both modes share the same local daemon + web architecture.

Web / Localhost (Default)

# Foreground mode — keeps the lifecycle command in the foreground (logs written to files)
pnpm tools-dev run web

# View recent logs:
pnpm tools-dev logs

# Background mode — daemon + web run as background processes
pnpm tools-dev start web

By default, tools-dev binds to available ephemeral ports and prints the actual URLs on startup. To use fixed ports from a stopped state:

pnpm tools-dev run web --daemon-port 17456 --web-port 17573

If daemon/web are already running, use restart to switch ports in the existing session:

pnpm tools-dev restart --daemon-port 17456 --web-port 17573

Desktop / Electron

# Start daemon + web + desktop in the background
pnpm tools-dev

# Check desktop status
pnpm tools-dev inspect desktop status

# Take a screenshot of the desktop app
pnpm tools-dev inspect desktop screenshot --path /tmp/open-design.png

The desktop app discovers the web URL automatically via sidecar IPC — no port guessing required.

Other Useful Commands

Command	What it does
`pnpm tools-dev status`	Show running sidecar statuses
`pnpm tools-dev logs`	Show daemon/web/desktop log tails
`pnpm tools-dev stop`	Stop all running sidecars
`pnpm tools-dev restart`	Stop then restart all sidecars
`pnpm tools-dev check`	Status + recent logs + common diagnostics

For fixed-port restarts, background startup, and full troubleshooting see QUICKSTART.md.

Nix

A flake is published at the repo root. Home Manager is the recommended path for individual developers; a NixOS module is also exposed for shared/server installs. See nix/README.md for the full surface (data dir, secrets, webFrontend vs. bringing your own server, OD_DAEMON_URL).

# Home Manager
inputs.open-design.url = "github:nexu-io/open-design";
# then: imports = [ inputs.open-design.homeManagerModules.default ];

nix run github:nexu-io/open-design       # boot the daemon (`od`) without installing

For developers, a Nix dev shell is available and can be used with direnv too:

nix develop   # dev shell with required dependencies to work on Open Design

Use Open Design from your coding agent

Open Design ships a stdio MCP server. Wire it into Claude Code, Codex, Cursor, VS Code, Antigravity, Zed, Windsurf, or any MCP-compatible client and the agent in another repo can read files from your local Open Design projects directly. Replaces the export-then-attach loop. When the agent calls search_files, get_file, or get_artifact without a project argument, the MCP defaults to whatever project (and file) you have open in Open Design right now, so prompts like "build this in my app" or "match these styles" just work.

Why MCP? Exporting and re-attaching a zip every design iteration breaks flow. The MCP server exposes your design source directly -- tokens CSS, JSX components, entry HTML -- as a structured API the agent can query by name. The agent always sees the live file, not a stale copy from the last export.

Open Settings → MCP server in the Open Design app for a per-client install flow. The panel bakes the absolute path to your node binary and the daemon's built cli.js into every snippet, so it works on a fresh source clone where od is not on your PATH. Cursor gets a one-click deeplink; the rest get a copy-paste JSON snippet in the schema their config file expects (Claude Code includes a claude mcp add-json one-liner so you do not have to hand-edit ~/.claude.json). Restart or reload your client after install for the server to show up.

The daemon must be running locally for MCP tool calls to succeed. If the agent was started before Open Design, restart the agent after Open Design is up so it can reach the live daemon. Tool calls made while the daemon is offline return a clear "daemon not reachable" error rather than a crash.

Security model. The MCP server is read-only; it exposes file reads, file metadata, and search -- nothing that writes to disk or calls an external service. It runs as a child process of the coding agent over stdio, so any MCP client you register inherits read access to your local Open Design projects. Treat it like installing a VS Code extension: only register clients you trust. The daemon binds to 127.0.0.1 by default; LAN-wide exposure requires an explicit OD_BIND_HOST opt-in. If you also front the SPA with a non-loopback static server, set OD_ALLOWED_ORIGINS=<origin1>,<origin2>,... (comma-separated scheme://host[:port] entries) so the daemon's same-origin gate accepts API writes from those origins on both the Origin and Host checks; without it the browser will see 403s on every PUT/POST (Caddy v2 reverse_proxy preserves the original Host header upstream by default, so loopback alone is not enough). Connector-credential and live-artifact preview routes stay loopback-only regardless.

Repository structure

open-design/
├── README.md                      ← this file
├── README.de.md                   ← Deutsch
├── README.ru.md                   ← Русский
├── README.zh-CN.md                ← 简体中文
├── QUICKSTART.md                  ← run / build / deploy guide
├── package.json                   ← pnpm workspace, single bin: od
│
├── apps/
│   ├── daemon/                    ← Node + Express, the only server
│   │   ├── src/                   ← TypeScript daemon source
│   │   │   ├── cli.ts             ← `od` bin source, compiled to dist/cli.js
│   │   │   ├── server.ts          ← /api/* routes (projects, chat, files, exports)
│   │   │   ├── agents.ts          ← PATH scanner + per-CLI argv builders
│   │   │   ├── claude-stream.ts   ← streaming JSON parser for Claude Code stdout
│   │   │   ├── skills.ts          ← SKILL.md frontmatter loader
│   │   │   └── db.ts              ← SQLite schema (projects/messages/templates/tabs)
│   │   ├── sidecar/               ← tools-dev daemon sidecar wrapper
│   │   └── tests/                 ← daemon package tests
│   │
│   └── web/                       ← Next.js 16 App Router + React client
│       ├── app/                   ← App Router entrypoints
│       ├── next.config.ts         ← dev rewrites + prod static export to out/
│       └── src/                   ← React + TypeScript client modules
│           ├── App.tsx            ← routing, bootstrap, settings
│           ├── components/        ← chat, composer, picker, preview, sketch, …
│           ├── prompts/
│           │   ├── system.ts      ← composeSystemPrompt(base, skill, DS, metadata)
│           │   ├── discovery.ts   ← turn-1 form + turn-2 branch + 5-dim critique
│           │   └── directions.ts  ← 5 visual directions × OKLch palette + font stack
│           ├── artifacts/         ← streaming <artifact> parser + manifests
│           ├── runtime/           ← iframe srcdoc, markdown, export helpers
│           ├── providers/         ← daemon SSE + BYOK API transports
│           └── state/             ← config + projects (localStorage + daemon-backed)
│
├── e2e/                           ← Playwright UI + external integration/Vitest harness
│
├── packages/
│   ├── contracts/                 ← shared web/daemon app contracts
│   ├── sidecar-proto/             ← Open Design sidecar protocol contract
│   ├── sidecar/                   ← generic sidecar runtime primitives
│   └── platform/                  ← generic process/platform primitives
│
├── skills/                        ← 31 SKILL.md skill bundles (27 prototype + 4 deck)
│   ├── web-prototype/             ← default for prototype mode
│   ├── saas-landing/  dashboard/  pricing-page/  docs-page/  blog-post/
│   ├── mobile-app/  mobile-onboarding/  gamified-app/
│   ├── email-marketing/  social-carousel/  magazine-poster/
│   ├── motion-frames/  sprite-animation/  digital-eguide/  dating-web/
│   ├── critique/  tweaks/  wireframe-sketch/
│   ├── pm-spec/  team-okrs/  meeting-notes/  kanban-board/
│   ├── eng-runbook/  finance-report/  invoice/  hr-onboarding/
│   ├── simple-deck/  replit-deck/  weekly-update/   ← deck mode
│   └── guizang-ppt/               ← bundled magazine-web-ppt (default for deck)
│       ├── SKILL.md
│       ├── assets/template.html   ← seed
│       └── references/{themes,layouts,components,checklist}.md
│
├── design-systems/                ← 72 DESIGN.md systems
│   ├── default/                   ← Neutral Modern (starter)
│   ├── warm-editorial/            ← Warm Editorial (starter)
│   ├── linear-app/  vercel/  stripe/  airbnb/  notion/  cursor/  apple/  …
│   └── README.md                  ← catalog overview
│
├── assets/
│   └── frames/                    ← shared device frames (used cross-skill)
│       ├── iphone-15-pro.html
│       ├── android-pixel.html
│       ├── ipad-pro.html
│       ├── macbook.html
│       └── browser-chrome.html
│
├── templates/
│   ├── deck-framework.html        ← deck baseline (nav / counter / print)
│   └── kami-deck.html             ← kami-flavored deck starter (parchment / ink-blue serif)
│
├── scripts/
│   └── sync-design-systems.ts     ← re-import upstream awesome-design-md tarball
│
├── docs/
│   ├── spec.md                    ← product spec, scenarios, differentiation
│   ├── architecture.md            ← topologies, data flow, components
│   ├── skills-protocol.md         ← extended SKILL.md od: frontmatter
│   ├── agent-adapters.md          ← per-CLI detection + dispatch
│   ├── modes.md                   ← prototype / deck / template / design-system
│   ├── references.md              ← long-form provenance
│   ├── roadmap.md                 ← phased delivery
│   ├── schemas/                   ← JSON schemas
│   └── examples/                  ← canonical artifact examples
│
└── .od/                           ← runtime data, gitignored, auto-created
    ├── app.sqlite                 ← projects / conversations / messages / tabs
    ├── projects/<id>/             ← per-project working folder (agent's cwd)
    └── artifacts/                 ← saved one-off renders

Design Systems

The 72 design systems library — style guide spread

72 systems out of the box, each as a single DESIGN.md:

Full catalog (click to expand)

AI & LLM — claude · cohere · mistral-ai · minimax · together-ai · replicate · runwayml · elevenlabs · ollama · x-ai

Developer Tools — cursor · vercel · linear-app · framer · expo · clickhouse · mongodb · supabase · hashicorp · posthog · sentry · warp · webflow · sanity · mintlify · lovable · composio · opencode-ai · voltagent

Productivity — notion · figma · miro · airtable · superhuman · intercom · zapier · cal · clay · raycast

Fintech — stripe · coinbase · binance · kraken · mastercard · revolut · wise

E-Commerce — shopify · airbnb · uber · nike · starbucks · pinterest

Media — spotify · playstation · wired · theverge · meta

Automotive — tesla · bmw · ferrari · lamborghini · bugatti · renault

Other — apple · ibm · nvidia · vodafone · sentry · resend · spacex

Starters — default (Neutral Modern) · warm-editorial

The product-system library is imported via scripts/sync-design-systems.ts from VoltAgent/awesome-design-md. Re-run to refresh. The 57 design skills are sourced from bergside/awesome-design-skills and added directly in design-systems/.

Visual directions

When the user has no brand spec, the agent emits a second form with five curated directions — the OD adaptation of huashu-design's "5 schools × 20 design philosophies" fallback. Each direction is a deterministic spec — palette in OKLch, font stack, layout posture cues, references — that the agent binds verbatim into the seed template's :root. One radio click → a fully specified visual system. No improvisation, no AI-slop.

Direction	Mood	Refs
Editorial — Monocle / FT	Print magazine, ink + cream + warm rust	Monocle · FT Weekend · NYT Magazine
Modern minimal — Linear / Vercel	Cool, structured, minimal accent	Linear · Vercel · Stripe
Tech utility	Information density, monospace, terminal	Bloomberg · Bauhaus tools
Brutalist	Raw, oversized type, no shadows, harsh accents	Bloomberg Businessweek · Achtung
Soft warm	Generous, low contrast, peachy neutrals	Notion marketing · Apple Health

Full spec → apps/daemon/src/prompts/directions.ts.

Media generation

OD doesn't stop at code. The same chat surface that produces <artifact> HTML also drives image, video, and audio generation, with model adapters wired into the daemon's media pipeline (apps/daemon/src/media-models.ts, apps/web/src/media/models.ts). Every render lands as a real file in the project workspace — .png for image, .mp4 for video — and shows up as a download chip when the turn ends.

Three model families carry the load today:

Surface	Model	Provider	What it's for
Image	`gpt-image-2`	Azure / OpenAI	Posters, profile avatars, illustrated maps, infographics, magazine-style social cards, photo restoration, exploded-view product art
Video	`seedance-2.0`	ByteDance Volcengine	15s cinematic t2v + i2v with audio — narrative shorts, character close-ups, product films, MV-style choreography
Video	`hyperframes-html`	HeyGen / OSS	HTML→MP4 motion graphics — product reveals, kinetic typography, data charts, social overlays, logo outros, TikTok-style verticals with karaoke captions

A growing prompt gallery at prompt-templates/ ships 93 ready-to-replicate prompts — 43 image (prompt-templates/image/*.json), 39 Seedance (prompt-templates/video/*.json excluding hyperframes-*), 11 HyperFrames (prompt-templates/video/hyperframes-*.json). Each carries a preview thumbnail, the prompt body verbatim, the target model, the aspect ratio, and a source block for license + attribution. The daemon serves them at GET /api/prompt-templates, the web app surfaces them as a card grid in the Image templates and Video templates tabs of the entry view; one click drops a prompt into the composer with the right model preselected.

gpt-image-2 — image gallery (sample of 43)

_{3D Stone Staircase Evolution Infographic
3-step infographic, hewn-stone aesthetic}

_{Illustrated City Food Map
Editorial hand-illustrated travel poster}

_{Cinematic Elevator Scene
Single-frame editorial fashion still}

_{Cyberpunk Anime Portrait
Profile avatar — neon face text}

_{Glamorous Woman in Black Portrait
Editorial studio portrait}

Full set → prompt-templates/image/. Sources: most pull from YouMind-OpenLab/awesome-gpt-image-prompts (CC-BY-4.0) with author attribution preserved per template.

Seedance 2.0 — video gallery (sample of 39)

_{Music Podcast & Guitar Technique
4K cinematic studio film}

_{Emotional Face Close-up
Cinematic micro-expression study}

_{Luxury Supercar Cinematic
Narrative product film}

_{Forbidden City Cat Satire
Stylised satire short}

_{Japanese Romance Short Film
15s Seedance 2.0 narrative}

Click any thumbnail to play the actual rendered MP4. Full set → prompt-templates/video/ (the *-seedance-* and Cinematic-tagged entries). Sources: YouMind-OpenLab/awesome-seedance-2-prompts (CC-BY-4.0) with original tweet links and author handles preserved.

HyperFrames — HTML→MP4 motion graphics (11 ready-to-replicate templates)

heygen-com/hyperframes is HeyGen's open-source agent-native video framework — you (or the agent) write HTML + CSS + GSAP, HyperFrames renders it to a deterministic MP4 via headless Chrome + FFmpeg. Open Design ships HyperFrames as a first-class video model (hyperframes-html) wired into the daemon dispatch, plus the skills/hyperframes/ skill that teaches the agent the timeline contract, scene-transition rules, audio-reactive patterns, captions/TTS, and the catalog blocks (npx hyperframes add <slug>).

Eleven hyperframes prompts ship under prompt-templates/video/hyperframes-*.json, each one a concrete brief that produces a specific archetype:

_{5s minimal product reveal · 16:9 · push-in title card with shader transition}	_{30s SaaS product promo · 16:9 · Linear/ClickUp-style with UI 3D reveals}	_{TikTok karaoke talking-head · 9:16 · TTS + word-synced captions}	_{30s brand sizzle reel · 16:9 · beat-synced kinetic typography, audio-reactive}
_{Animated bar-chart race · 16:9 · NYT-style data infographic}	_{Flight map (origin → dest) · 16:9 · Apple-style cinematic route reveal}	_{4s cinematic logo outro · 16:9 · piece-by-piece assembly + bloom}	_{$0 → $10K money counter · 9:16 · Apple-style hype with green flash + burst}
_{3-phone app showcase · 16:9 · floating phones with feature callouts}	_{Social overlay stack · 9:16 · X · Reddit · Spotify · Instagram in sequence}	_{Website-to-video pipeline · 16:9 · captures site at 3 viewports + transitions}

Pattern is the same as the rest: pick a template, edit the brief, send. The agent reads the bundled skills/hyperframes/SKILL.md (which carries the OD-specific render workflow — composition source files into a .hyperframes-cache/ so they don't clutter the file workspace, daemon dispatches npx hyperframes render to dodge the macOS sandbox-exec / Puppeteer hang, only the final .mp4 lands as a project chip), authors the composition, and ships an MP4. Catalog block thumbnails © HeyGen, served from their CDN; the OSS framework itself is Apache-2.0.

Also wired but not surfaced as templates yet: Kling 2.0 / 1.6 / 1.5, Veo 3 / Veo 2, Sora 2 / Sora 2-Pro (via Fal), MiniMax video-01 — all live in VIDEO_MODELS (apps/web/src/media/models.ts). Suno v5 / v4.5, Udio v2, Lyria 2 (music) and gpt-4o-mini-tts, MiniMax TTS (speech) cover the audio surface. Templates for these are open contributions — drop a JSON into prompt-templates/video/ or prompt-templates/audio/ and it shows up in the picker.

Beyond chat — what else ships

The chat / artifact loop gets the spotlight, but a handful of less-visible capabilities are already wired and worth knowing before you compare OD to anything else:

Claude Design ZIP import. Drop an export from claude.ai onto the welcome dialog. POST /api/import/claude-design extracts it into a real .od/projects/<id>/, opens the entry file as a tab, and stages a continue-where-Anthropic-left-off prompt for your local agent. No re-prompting, no "ask the model to re-create what we just had". (apps/daemon/src/server.ts — /api/import/claude-design)
Multi-provider BYOK proxy. POST /api/proxy/{anthropic,openai,azure,google}/stream takes { baseUrl, apiKey, model, messages }, builds the provider-specific upstream request, normalizes SSE chunks into delta/end/error, and allows loopback local LLM providers while rejecting non-loopback private, link-local, CGNAT, multicast, reserved, and redirect targets to head off SSRF. OpenAI-compatible covers OpenAI, Azure AI Foundry /openai/v1, DeepSeek, Groq, MiMo, OpenRouter, Ollama, LM Studio, and self-hosted vLLM; Azure OpenAI adds deployment URL + api-version; Google uses Gemini :streamGenerateContent.
User-saved templates. Once you like a render, POST /api/templates snapshots the HTML + metadata into the SQLite templates table. The next project picks it from a "your templates" row in the picker — same surface as the shipped 31, but yours.
Tab persistence. Every project remembers its open files and active tab in the tabs table. Reopen the project tomorrow and the workspace looks exactly the way you left it.
Artifact lint API. POST /api/artifacts/lint runs structural checks on a generated artifact (broken <artifact> framing, missing required side files, stale palette tokens) and returns findings the agent can read back into its next turn. The five-dim self-critique uses this to ground its score in real evidence, not vibes.
Sidecar protocol + desktop automation. Daemon, web, and desktop processes carry typed five-field stamps (app · mode · namespace · ipc · source) and expose a JSON-RPC IPC channel at /tmp/open-design/ipc/<namespace>/<app>.sock. tools-dev inspect desktop status \| eval \| screenshot drives that channel, so headless E2E works against a real Electron shell without bespoke harnesses (packages/sidecar-proto/, apps/desktop/src/main/).
Windows-friendly spawning. Every adapter that would otherwise blow CreateProcess's ~32 KB argv limit on long composed prompts (Codex, Gemini, OpenCode, Cursor Agent, Qwen, Qoder CLI, Pi) feeds the prompt over stdin instead. Claude Code and Copilot keep -p; the daemon falls back to a temp prompt-file when even that overflows.
Per-namespace runtime data. OD_DATA_DIR and --namespace give you fully isolated .od/-style trees, so Playwright, beta channels, and your real projects never share a SQLite file.

Anti-AI-slop machinery

The whole machinery below is the huashu-design playbook, ported into OD's prompt-stack and made enforceable per-skill via the side-file pre-flight. Read apps/daemon/src/prompts/discovery.ts for the live wording:

Question form first. Turn 1 is <question-form> only — no thinking, no tools, no narration. The user chooses defaults at radio speed.
Brand-spec extraction. When the user attaches a screenshot or URL, the agent runs a five-step protocol (locate · download · grep hex · codify brand-spec.md · vocalise) before writing CSS. Never guesses brand colors from memory.
Five-dim critique. Before emitting <artifact>, the agent silently scores its output 1–5 across philosophy / hierarchy / execution / specificity / restraint. Anything under 3/5 is a regression — fix and rescore. Two passes is normal.
P0/P1/P2 checklist. Every skill ships a references/checklist.md with hard P0 gates. The agent must pass P0 before emitting.
Slop blacklist. Aggressive purple gradients, generic emoji icons, rounded card with left-border accent, hand-drawn SVG humans, Inter as a display face, invented metrics — explicitly forbidden in the prompt.
Honest placeholders > fake stats. When the agent doesn't have a real number, it writes — or a labelled grey block, not "10× faster".

Comparison

Axis	Claude Design (Anthropic)	Open CoDesign	Open Design
License	Closed	MIT	Apache-2.0
Form factor	Web (claude.ai)	Desktop (Electron)	Web app + local daemon
Deployable on Vercel	❌	❌	✅
Agent runtime	Bundled (Opus 4.7)	Bundled (`pi-ai`)	Delegated to user's existing CLI
Skills	Proprietary	12 custom TS modules + `SKILL.md`	31 file-based `SKILL.md` bundles, droppable
Design system	Proprietary	`DESIGN.md` (v0.2 roadmap)	`DESIGN.md` × 129 systems shipped
Provider flexibility	Anthropic only	7+ via `pi-ai`	16 CLI adapters + OpenAI-compatible BYOK proxy
Init question form	❌	❌	✅ Hard rule, turn 1
Direction picker	❌	❌	✅ 5 deterministic directions
Live todo progress + tool stream	❌	✅	✅ (UX pattern from open-codesign)
Sandboxed iframe preview	❌	✅	✅ (pattern from open-codesign)
Claude Design ZIP import	n/a	❌	✅ `POST /api/import/claude-design` — keep editing where Anthropic left off
Comment-mode surgical edits	❌	✅	🟡 partial — preview element comments + chat attachments; surgical patch reliability still in progress
AI-emitted tweaks panel	❌	✅	🚧 roadmap — dedicated chat-side panel UX is not implemented yet
Filesystem-grade workspace	❌	partial (Electron sandbox)	✅ Real cwd, real tools, persisted SQLite (projects · conversations · messages · tabs · templates)
5-dim self-critique	❌	❌	✅ Pre-emit gate
Artifact lint	❌	❌	✅ `POST /api/artifacts/lint` — findings fed back to the agent
Sidecar IPC + headless desktop	❌	❌	✅ Stamped processes + `tools-dev inspect desktop status \| eval \| screenshot`
Export formats	Limited	HTML / PDF / PPTX / ZIP / Markdown	HTML / PDF / PPTX (agent-driven) / ZIP / Markdown
PPT skill reuse	N/A	Built-in	`guizang-ppt-skill` drops in (default for deck mode)
Minimum billing	Pro / Max / Team	BYOK	BYOK — paste any OpenAI-compatible `baseUrl`

Supported coding agents

Auto-detected from PATH on daemon boot. No config required. Streaming dispatch lives in apps/daemon/src/agents.ts (AGENT_DEFS); per-CLI parsers live alongside it. Models are populated either by probing <bin> --list-models / <bin> models / ACP handshake, or from a curated fallback list when the CLI doesn't expose a list.

Agent	Bin	Stream format	Argv shape (composed prompt path)
Claude Code	`claude`	`claude-stream-json` (typed events)	`claude -p <prompt> --output-format stream-json --verbose [--include-partial-messages] [--add-dir …] --permission-mode bypassPermissions`
Codex CLI	`codex`	`json-event-stream` + `codex` parser	`codex exec --json --skip-git-repo-check --sandbox workspace-write -c sandbox_workspace_write.network_access=true [-C cwd] [--add-dir …] [--model …] [-c model_reasoning_effort=…]` (prompt on stdin)
Devin for Terminal	`devin`	`acp-json-rpc`	`devin --permission-mode dangerous --respect-workspace-trust false acp`
Gemini CLI	`gemini`	`json-event-stream` + `gemini` parser	`GEMINI_CLI_TRUST_WORKSPACE=true gemini --output-format stream-json --yolo [--model …]` (prompt on stdin)
OpenCode	`opencode`	`json-event-stream` + `opencode` parser	`opencode run --format json --dangerously-skip-permissions [--model …] -` (prompt on stdin)
Cursor Agent	`cursor-agent`	`json-event-stream` + `cursor-agent` parser	`cursor-agent --print --output-format stream-json --stream-partial-output --force --trust [--workspace cwd] [--model …] -` (prompt on stdin)
Qwen Code	`qwen`	`plain` (raw stdout chunks)	`qwen --yolo [--model …] -` (prompt on stdin)
Qoder CLI	`qodercli`	`qoder-stream-json` (typed events)	`qodercli -p --output-format stream-json --permission-mode bypass_permissions [--cwd cwd] [--model …] [--add-dir …]` (prompt on stdin)
GitHub Copilot CLI	`copilot`	`copilot-stream-json` (typed events)	`copilot -p <prompt> --allow-all-tools --output-format json [--model …] [--add-dir …]`
Hermes	`hermes`	`acp-json-rpc` (Agent Client Protocol)	`hermes acp --accept-hooks`
Kimi CLI	`kimi`	`acp-json-rpc`	`kimi acp`
Kiro CLI	`kiro-cli`	`acp-json-rpc`	`kiro-cli acp`
Kilo	`kilo`	`acp-json-rpc`	`kilo acp`
Mistral Vibe CLI	`vibe-acp`	`acp-json-rpc`	`vibe-acp`
DeepSeek TUI	`deepseek`	`plain` (raw stdout chunks)	`deepseek exec --auto [--model …] <prompt>` (prompt as positional arg)
Pi	`pi`	`pi-rpc` (stdio JSON-RPC)	`pi --mode rpc [--model …] [--thinking …]` (prompt sent as RPC `prompt` command)
Multi-provider BYOK	n/a	SSE normalization	`POST /api/proxy/{provider}/stream` → Anthropic / OpenAI-compatible / Azure OpenAI / Gemini; SSRF-guarded with loopback local providers allowed, non-loopback internal ranges blocked, and upstream redirects disabled

Adding a new CLI is one entry in apps/daemon/src/agents.ts. Streaming format is one of claude-stream-json, qoder-stream-json, copilot-stream-json, json-event-stream (with a per-CLI eventParser), acp-json-rpc, pi-rpc, or plain.

References & lineage

Every external project this repo borrows from. Each link goes to the source so you can verify the provenance.

Project	Role here
`Claude Design`	The closed-source product this repo is the open-source alternative to.
`alchaincyf/huashu-design`	The design-philosophy core. Junior-Designer workflow, the 5-step brand-asset protocol, anti-AI-slop checklist, 5-dimensional self-critique, and the "5 schools × 20 design philosophies" library behind our direction picker — all distilled into `apps/daemon/src/prompts/discovery.ts` and `apps/daemon/src/prompts/directions.ts`.
`op7418/guizang-ppt-skill`	Magazine-web-PPT skill bundled verbatim under `skills/guizang-ppt/` with original LICENSE preserved. Default for deck mode. P0/P1/P2 checklist culture borrowed for every other skill.
`multica-ai/multica`	The daemon + adapter architecture. PATH-scan agent detection, local daemon as the only privileged process, agent-as-teammate worldview. We adopt the model; we do not vendor the code.
`OpenCoworkAI/open-codesign`	The first open-source Claude-Design alternative and our closest peer. UX patterns adopted: streaming-artifact loop, sandboxed-iframe preview (vendored React 18 + Babel), live agent panel (todos + tool calls + interruptible), five-format export list (HTML/PDF/PPTX/ZIP/Markdown), local-first storage hub, `SKILL.md` taste-injection, and the first pass of comment-mode preview annotations. UX patterns still on our roadmap: full surgical-edit reliability and AI-emitted tweaks panel. We deliberately do not vendor `pi-ai` — open-codesign bundles it as the agent runtime; we delegate to whichever CLI the user already has.
`VoltAgent/awesome-claude-design` / `awesome-design-md`	Source of the 9-section `DESIGN.md` schema and 70 product systems imported via `scripts/sync-design-systems.ts`.
`bergside/awesome-design-skills`	Source of 57 design skills added directly as normalized `DESIGN.md` files under `design-systems/`.
`farion1231/cc-switch`	Inspiration for symlink-based skill distribution across multiple agent CLIs.
Claude Code skills	The `SKILL.md` convention adopted verbatim — any Claude Code skill drops into `skills/` and is picked up by the daemon.

Long-form provenance write-up — what we take from each, what we deliberately don't — lives at docs/references.md.

Roadmap

Daemon + agent detection (16 CLI adapters) + skill registry + design-system catalog
Web app + chat + question form + 5-direction picker + todo progress + sandboxed preview
31 skills + 72 design systems + 5 visual directions + 5 device frames
SQLite-backed projects · conversations · messages · tabs · templates
Multi-provider BYOK proxy (/api/proxy/{anthropic,openai,azure,google}/stream) with SSRF guard
Claude Design ZIP import (/api/import/claude-design)
Sidecar protocol + Electron desktop with IPC automation (STATUS / EVAL / SCREENSHOT / CONSOLE / CLICK / SHUTDOWN)
Artifact lint API + 5-dim self-critique pre-emit gate
Comment-mode surgical edits — partial shipped: preview element comments and chat attachments; reliable targeted patching remains in progress
AI-emitted tweaks panel UX — not implemented yet
Vercel + tunnel deployment recipe (Topology B)
One-command npx od init to scaffold a project with DESIGN.md
Skill marketplace (od skills install <github-repo>) and od skill add | list | remove | test CLI surface (drafted in docs/skills-protocol.md, implementation pending)
Packaged Electron build out of apps/packaged/ — macOS (Apple Silicon) and Windows (x64) downloads on open-design.ai and the GitHub releases page

Phased delivery → docs/roadmap.md.

Status

This is an early implementation — the closed loop (detect → pick skill + design system → chat → parse <artifact> → preview → save) runs end-to-end. The prompt stack and skill library are where most of the value lives, and they're stable. The component-level UI is shipping daily.

Stay in the loop

Follow @nexudotio on X for release notes, new skills, new design systems, and the occasional behind-the-scenes thread on what's shipping next. Discord is for chat, X is for the milestones — both links are in the badges above.

Star us

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, real signal: github.com/nexu-io/open-design.

Contributing

Issues, PRs, new skills, and new design systems are all welcome. The highest-leverage contributions are usually one folder, one Markdown file, or one PR-sized adapter:

Add a skill — drop a folder into skills/ following the SKILL.md convention.
Add a design system — drop a DESIGN.md into design-systems/<brand>/ using the 9-section schema.
Wire up a new coding-agent CLI — one entry in apps/daemon/src/agents.ts.

Full walkthrough, bar-for-merging, code style, and what we don't accept → CONTRIBUTING.md (Deutsch, Français, 简体中文).

Contributors

Thanks to everyone who has helped move Open Design forward — through code, docs, feedback, new skills, new design systems, or even a sharp issue. Every real contribution counts, and the wall below is the easiest way to say so out loud.

If you've shipped your first PR — welcome. The good-first-issue/help-wanted label is the entry point.

Repository activity

The SVG above is regenerated daily by .github/workflows/metrics.yml using lowlighter/metrics. Trigger a manual refresh from the Actions tab if you want it sooner; for richer plugins (traffic, follow-up time), add a METRICS_TOKEN repository secret with a fine-grained PAT.

Star History

If the curve bends up, that's the signal we look for. ★ this repo to push it.

Credits

The HTML PPT Studio family of skills — the master skills/html-ppt/ and the per-template wrappers under skills/html-ppt-*/ (15 full-deck templates, 36 themes, 31 single-page layouts, 27 CSS animations + 20 canvas FX, the keyboard runtime, and the magnetic-card presenter mode) — are integrated from the open-source project lewislulu/html-ppt-skill (MIT). The upstream LICENSE ships in-tree at skills/html-ppt/LICENSE and authorship credit goes to @lewislulu. Each per-template Examples card (html-ppt-pitch-deck, html-ppt-tech-sharing, html-ppt-presenter-mode, html-ppt-xhs-post, …) delegates authoring guidance to the master skill so the upstream's prompt → output behavior is preserved end-to-end when you click Use this prompt.

The magazine / horizontal-swipe deck flow under skills/guizang-ppt/ is integrated from op7418/guizang-ppt-skill (MIT). Authorship credit goes to @op7418.

License

Apache-2.0. The bundled skills/guizang-ppt/ retains its original LICENSE (MIT) and authorship attribution to op7418. The bundled skills/html-ppt/ retains its original LICENSE (MIT) and authorship attribution to lewislulu.

README.md Unescape Escape