Skip to content
Back to search

pi-design-deck

Visual design deck for presenting multi-slide options with high-fidelity previews

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

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

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nicobailon/pi-design-deck with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nicobailon/pi-design-deck'

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

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nicobailon--pi-design-deck/badge.svg)](/listings/nicobailon--pi-design-deck)

HTML

<a href="/listings/nicobailon--pi-design-deck"><img src="/api/listings/nicobailon--pi-design-deck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

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

pi install npm:pi-design-deck

Restart pi to load the extension and the bundled `design-deck` skill.

**Requirements:** - pi-agent v0.35.0 or later (extensions API) - For native macOS window: `pi install npm:glimpseui` (optional, falls back to browser if not installed)

https://github.com/user-attachments/assets/aff1bac6-8bc2-461a-8828-f588ce655f7f

What was scanned

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

README.md · README · 365 lines

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

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

  1. <p>
  2. <img src="banner.png" alt="pi-design-deck" width="1100">
  3. </p>
  4. # Design Deck
  5. A tool for [Pi coding agent](https://github.com/badlogic/pi-mono/) that presents multi-slide visual decision decks. On macOS, uses [Glimpse](https://github.com/nicobailon/glimpseui) to render in a native WKWebView window; falls back to a browser tab on other platforms. Each slide shows 2-4 high-fidelity previews — code diffs, architecture diagrams, UI mockups — and you pick one per slide. The agent gets back a clean selection map and moves on to implementation.
  6. <img width="1340" alt="Design Deck screenshot" src="https://github.com/user-attachments/assets/20864ac6-9223-4e2e-ba3c-db3eaae0abd8" />
  7. ## Usage
  8. Just ask. The agent reaches for the design deck when visual comparison makes sense.
  9. ```
  10. show me 3 architecture options for the backend
  11. present a few UI directions for the settings page
  12. what are my options for the auth flow? show me visually
  13. read the PRD at docs/api-plan.md and present the key decisions
  14. ```
  15. Three slash commands are also available for more structured flows:
  16. - **`/deck`** — general purpose. Give it a topic or run it bare.
  17. - **`/deck-plan docs/plan.md`** — reads a plan or PRD, identifies decision points, builds slides for each.
  18. - **`/deck-discover`** — interviews you first to gather requirements, then builds a deck from what it learned.
  19. ## Why
  20. The interview tool gathers structured input — you answer questions. The design deck is the other direction: the agent shows you visual options and you pick. They work together — interview discovers requirements, deck presents the resulting options — but they're distinct tools for distinct jobs.
  21. The persistent server architecture means the browser stays open across tool re-invocations. When you click "Generate another option," the agent creates it and pushes it into the live deck via SSE — no page reloads, no lost state.
  22. ## Install
  23. ```bash
  24. pi install npm:pi-design-deck
  25. ```
  26. Restart pi to load the extension and the bundled `design-deck` skill.
  27. **Requirements:**
  28. - pi-agent v0.35.0 or later (extensions API)
  29. - For native macOS window: `pi install npm:glimpseui` (optional, falls back to browser if not installed)
  30. https://github.com/user-attachments/assets/aff1bac6-8bc2-461a-8828-f588ce655f7f
  31. ## Quick Start
  32. The agent builds slides as JSON. Each slide is one decision, each option is one approach:
  33. ```json
  34. {
  35. "title": "API Design",
  36. "slides": [
  37. {
  38. "id": "auth",
  39. "title": "Authentication Strategy",
  40. "context": "Choose how users authenticate with the API.",
  41. "columns": 2,
  42. "options": [
  43. {
  44. "label": "JWT + Refresh Tokens",
  45. "description": "Stateless, horizontally scalable",
  46. "aside": "Tokens are self-contained — no session store needed.\nWatch for token size with many claims.",
  47. "previewBlocks": [
  48. { "type": "code", "code": "const token = jwt.sign({ sub: user.id }, SECRET, { expiresIn: '15m' });\nres.cookie('refresh', refreshToken, { httpOnly: true });", "lang": "ts" },
  49. { "type": "mermaid", "content": "sequenceDiagram\n Client->>API: POST /login\n API->>Client: JWT + refresh cookie\n Client->>API: GET /data (Bearer JWT)\n API->>Client: 200 OK" }
  50. ],
  51. "recommended": true
  52. },
  53. {
  54. "label": "Session Cookies",
  55. "description": "Server-side sessions with Redis backing",
  56. "aside": "Simple mental model. Session invalidation is instant.\nRequires sticky sessions or shared session store.",
  57. "previewBlocks": [
  58. { "type": "code", "code": "app.use(session({ store: new RedisStore({ client }), secret: SECRET }));", "lang": "ts" },
  59. { "type": "mermaid", "content": "sequenceDiagram\n Client->>API: POST /login\n API->>Redis: Store session\n API->>Client: Set-Cookie: sid=...\n Client->>API: GET /data (Cookie)\n API->>Redis: Lookup session" }
  60. ]
  61. }
  62. ]
  63. }
  64. ]
  65. }
  66. ```
  67. The browser opens, the user picks "JWT + Refresh Tokens", and the agent receives:
  68. ```
  69. { "auth": "JWT + Refresh Tokens" }
  70. ```
  71. ## Features
  72. - **Preview blocks**: Four typed block types — `code` (Prism.js syntax highlighting), `mermaid` (Mermaid.js diagrams), `html` (raw HTML), and `image` (served from disk). Mix freely within one option.
  73. - **Raw HTML previews**: Full `previewHtml` support for custom UI mockups with inline styles. Use when blocks aren't enough.
  74. - **Generate-more loop**: Users click "Generate another option" and the agent pushes a new option into the live deck via SSE. No page reload.
  75. - **Model selector**: Dropdown to pick which model generates new options. Save as default, or override per-request.
  76. - **Thinking level**: Adjust reasoning effort for option generation when the selected model supports it.
  77. - **Slide columns**: `columns` property (1, 2, 3, or 4) per slide. Auto-detected from option count if omitted.
  78. - **Smart rebalancing**: Grid layout recalculates after generate-more adds options to minimize orphans.
  79. - **Option aside**: Explanatory text rendered below the preview. Supports `\n` for line breaks.
  80. - **Save/load snapshots**: `Cmd+S` saves the deck to disk. Use `action: "list"` to enumerate saved decks, `action: "open"` to reopen one by deck ID, or pass a file path to `slides`.
  81. - **Feedback and pinned comments**: Write feedback on any option, not just the one you pick. Press `C` and click anywhere on a preview or image to pin a numbered comment you can drag, edit or delete. The agent receives every note and pin with its position, for example `#2 (image 1, 62%, 18%): logo too small`, and saved decks restore them along with the summary's final instructions.
  82. - **Full-size images**: The maximize button on an image opens it at full resolution. Zoom with the scroll wheel or a pinch, drag to pan, and pin comments there too.
  83. - **Standalone HTML export**: `action: "export"` writes a read-only `export.html` next to the saved deck snapshot.
  84. - **Light/dark/auto theme**: Full theme toggle with `Cmd+Shift+L` (configurable). Persists in localStorage.
  85. - **Heartbeat watchdog**: Server detects lost browser connections (60s grace) and cleans up.
  86. - **Idle timeout**: 5-minute inactivity timer after generate-more. Closes the deck if the agent doesn't respond.
  87. - **Escape confirmation**: Once you've picked or written anything, Escape shows a confirmation bar before cancelling.
  88. - **ARIA / keyboard**: `role="radiogroup"` on options, arrow key navigation, Space/Enter to select, number keys for quick pick. Shortcuts never fire while you type in a field.
  89. ## How It Works
  90. 1. Agent calls `design_deck()` with slides JSON — local HTTP server starts, opens in Glimpse on macOS when available, otherwise opens in the browser
  91. 2. User navigates slides, picks one option per slide
  92. 3. Optionally clicks "Generate N options" — agent generates and pushes via `add-options`, deck stays open
  93. 4. User submits — selections returned to agent as `{ slideId: "selected label" }`
  94. The server persists across tool re-invocations. When generate-more fires, the tool resolves with instructions for the agent to create a new option. The browser shows a skeleton placeholder with shimmer animation until the new option arrives via SSE.
  95. ## Slides
  96. ### previewBlocks vs previewHtml
  97. Every option needs exactly one of `previewBlocks` or `previewHtml` (not both, not neither).
  98. **previewBlocks** — structured array of typed blocks, rendered in order:
  99. | Block | Required Fields | Description |
  100. |-------|----------------|-------------|
  101. | `code` | `code`, `lang` | Syntax-highlighted code (Prism.js + autoloader) |
  102. | `mermaid` | `content` | Mermaid diagram. Optional `theme` object for per-block overrides |
  103. | `html` | `content` | Raw HTML snippet |
  104. | `image` | `src`, `alt` | Image from disk (absolute path). Optional `caption` |
  105. ```json
  106. {
  107. "previewBlocks": [
  108. { "type": "mermaid", "content": "graph TD\n A-->B-->C" },
  109. { "type": "code", "code": "export default router;", "lang": "ts" },
  110. { "type": "html", "content": "<div style='color:#888'>Implementation notes...</div>" }
  111. ]
  112. }
  113. ```
  114. **previewHtml** — raw HTML string injected directly into the preview container. Full control over styling:
  115. ```json
  116. {
  117. "previewHtml": "<div style='font-family: system-ui; padding: 16px'><h3>Dashboard Layout</h3><div style='display: grid; grid-template-columns: 200px 1fr'>...</div></div>"
  118. }
  119. ```
  120. ### Image Blocks
  121. Image blocks reference absolute file paths. The server copies each file into a temp directory and serves it via `/assets/` — the browser never sees the original path. Cleanup happens when the deck closes.
  122. ### Columns
  123. Each slide supports `columns: 1 | 2 | 3 | 4` to control the grid layout. Omit it and the deck auto-detects based on option count. Use `columns: 1` for wide architecture diagrams, `columns: 2` for side-by-side comparisons, `columns: 4` for many small items.
  124. ### Aside
  125. The `aside` field renders explanatory text below the preview with styled typography. Use `\n` for line breaks. Good for trade-off summaries, pros/cons, or implementation notes that complement the visual preview.
  126. ### Reserved IDs
  127. The slide ID `"summary"` is reserved for the built-in summary slide that appears after all user slides. Don't use it.
  128. ## Generate-More Loop
  129. When the user clicks "Generate N options," the tool resolves with a structured prompt telling the agent which slide needs options, how many, what options already exist, and what format to use. The agent generates the requested options and pushes them all at once:
  130. ```typescript
  131. design_deck({
  132. action: "add-options",
  133. slideId: "arch",
  134. options: '[{"label": "Serverless", "previewBlocks": [...]}, {"label": "Edge", "previewBlocks": [...]}]'
  135. })
  136. ```
  137. The browser shows the new options with entry animations. The `add-options` call blocks until the next user action (submit, cancel, or another generate-more).
  138. ### Model Override
  139. The deck shows a model dropdown when 2+ models are available. Users pick which model generates new options. When a model other than the current one is selected, the generate-more result instructs the agent to use the built-in `deck_generate` tool, which spawns pi headlessly with that model.
  140. The default model can be set in the UI (saved to settings) or in `settings.json`:
  141. ```json
  142. {
  143. "designDeck": {
  144. "generateModel": "google/gemini-3.1-pro"
  145. }
  146. }
  147. ```
  148. Priority: browser selection > settings default > current model.
  149. ### Prompt Input
  150. An optional text input next to the generate button lets users provide instructions that flow through to the agent (e.g., "make it more minimal" or "use WebSockets instead").
  151. ## Saving and Loading
  152. **Manual save:** Press `Cmd+S` (or `Ctrl+S`) at any time to save the current deck state to disk.
  153. **Auto-save on submit:** Enabled by default. Saves a snapshot after successful submission with a `-submitted` suffix.
  154. **Auto-save on cancel:** If you cancel a deck that has selections, it's automatically saved with a `-cancelled` suffix. This makes it easy to recover work if you accidentally close the tab or change your mind.
  155. **Loading a saved deck:**
  156. ```typescript
  157. design_deck({ slides: "~/.pi/deck-snapshots/api-design-myapp-main-2026-02-22-143000/deck.json" })
  158. ```
  159. The deck opens with selections pre-populated and image paths resolved relative to the snapshot directory.
  160. **Listing saved decks:**
  161. ```typescript
  162. design_deck({ action: "list" })
  163. ```
  164. **Opening by deck ID:**
  165. ```typescript
  166. design_deck({ action: "open", deckId: "api-design-myapp-main-2026-02-22-143000-submitted" })
  167. ```
  168. **Exporting standalone HTML:**
  169. ```typescript
  170. design_deck({ action: "export", deckId: "api-design-myapp-main-2026-02-22-143000-submitted", format: "html" })
  171. ```
  172. **Snapshot structure:**
  173. ```
  174. ~/.pi/deck-snapshots/
  175. {title}-{project}-{branch}-{date}-{time}[-submitted|-cancelled]/
  176. deck.json # Config + selections + metadata
  177. images/ # Copied image assets (relative paths in JSON)
  178. ```
  179. ## Keyboard Shortcuts
  180. | Key | Action |
  181. |-----|--------|
  182. | `←` / `→` | Previous / next slide (when a card has focus, arrow keys move between options) |
  183. | `Space` / `Enter` | Select the focused option |
  184. | `1`-`9` | Quick-select option by number |
  185. | `C` | Comment mode: click a preview or image to pin a comment |
  186. | `Cmd/Ctrl+Enter` | Submit (opens the summary if a slide still needs a pick) |
  187. | `Cmd/Ctrl+S` | Save deck snapshot |
  188. | `Cmd+Shift+L` | Toggle theme (configurable) |
  189. | `Escape` | Close the open comment, then leave comment mode, then cancel (confirmation bar if you've picked or written anything) |
  190. Shortcuts are ignored while you type in a field, except `Cmd/Ctrl+S` and `Cmd/Ctrl+Enter`. In a comment, `Enter` saves and `Shift+Enter` adds a line. In the image viewer, `+`, `-` and `0` zoom in, zoom out and fit, and `Escape` or a click outside closes it.
  191. ## Configuration
  192. Settings in `~/.pi/agent/settings.json` under the `designDeck` key:
  193. ```json
  194. {
  195. "designDeck": {
  196. "port": 0,
  197. "browser": "chrome",
  198. "snapshotDir": "~/.pi/deck-snapshots",
  199. "autoSaveOnSubmit": true,
  200. "generateModel": "google/gemini-3.1-pro",
  201. "theme": {
  202. "mode": "dark",
  203. "toggleHotkey": "mod+shift+l"
  204. }
  205. }
  206. }
  207. ```
  208. | Setting | Default | Description |
  209. |---------|---------|-------------|
  210. | `port` | `0` (random) | Fixed port for the deck server |
  211. | `browser` | System default | Browser app to open (e.g., `"chrome"`, `"firefox"`) |
  212. | `snapshotDir` | `~/.pi/deck-snapshots` | Directory for saved deck snapshots |
  213. | `autoSaveOnSubmit` | `true` | Auto-save snapshot on successful submit |
  214. | `generateModel` | — | Default model for generate-more (e.g., `"google/gemini-3.1-pro"`) |
  215. | `theme.mode` | `"dark"` | `"dark"`, `"light"`, or `"auto"` (follows OS) |
  216. | `theme.toggleHotkey` | `"mod+shift+l"` | Hotkey string to toggle theme |
  217. **Migration:** If you previously had `deckGenerateModel` under the `interview` key, it's automatically migrated to `designDeck.generateModel` on first load.
  218. ## Tool Parameters
  219. The agent handles these when you use the slash commands or ask in natural language. This documents the underlying tool API.
  220. | Parameter | Type | Description |
  221. |-----------|------|-------------|
  222. | `slides` | string | JSON string of deck config, or file path to a saved deck |
  223. | `action` | `"add-options"` \| `"add-option"` \| `"replace-options"` \| `"list"` \| `"open"` \| `"export"` | Push/replace options, list saved decks, reopen a saved deck, or export one |
  224. | `slideId` | string | Target slide ID (required with actions) |
  225. | `option` | string | JSON string of one option (required with `add-option`) |
  226. | `options` | string | JSON string of option array (required with `add-options` or `replace-options`) |
  227. | `deckId` | string | Saved deck ID from `action: "list"` (required with `open` / `export`) |
  228. | `format` | string | Export format for `action: "export"` (`"html"` currently supported) |
  229. Six modes of invocation:
  230. 1. **Start a new deck:** `design_deck({ slides: "<JSON>" })`
  231. 2. **Add options to running deck:** `design_deck({ action: "add-options", slideId: "...", options: "<JSON array>" })` — blocks until next user action
  232. 3. **Add single option (non-blocking):** `design_deck({ action: "add-option", slideId: "...", option: "<JSON>" })`
  233. 4. **Replace all options on a slide:** `design_deck({ action: "replace-options", slideId: "...", options: "<JSON array>" })`
  234. 5. **List saved decks:** `design_deck({ action: "list" })`
  235. 6. **Open or export a saved deck:** `design_deck({ action: "open" | "export", deckId: "..." })`
  236. ## File Structure
  237. ```
  238. pi-design-deck/
  239. ├── index.ts # Tool registration, module-level state, lifecycle
  240. ├── generate-prompts.ts # Prompt builders for generate-more / regenerate
  241. ├── model-runner.ts # Headless pi spawner for deck_generate tool
  242. ├── deck-schema.ts # TypeScript types and validation (no dependencies)
  243. ├── deck-server.ts # HTTP server, SSE, asset serving, snapshots
  244. ├── server-utils.ts # Shared HTTP/session utilities
  245. ├── settings.ts # Settings with designDeck namespace + migration
  246. ├── schema.test.ts # 48 tests across 3 describe blocks
  247. ├── form/
  248. │ ├── deck.html # HTML template (loads CSS/JS, Prism, Mermaid)
  249. │ ├── css/ # Theme variables, layout, preview blocks, controls
  250. │ └── js/ # Client: state, rendering, interaction, session
  251. ├── prompts/
  252. │ ├── deck.md # /deck — general purpose
  253. │ ├── deck-plan.md # /deck-plan — design from plan/PRD
  254. │ └── deck-discover.md # /deck-discover — interview then design
  255. └── skills/
  256. └── design-deck/
  257. └── SKILL.md # Agent skill for on-demand loading
  258. ```
  259. ## Bundled Skill
  260. The extension includes a `design-deck` skill at `skills/design-deck/SKILL.md` that teaches the agent when a deck beats a plain question, how to structure slides, which preview format fits, and how to make options that are real alternatives instead of color swaps. The generate-more and regenerate steps are spelled out in the tool's own replies, so the skill stays short (about 1.4k tokens).
  261. The skill is declared in `package.json` under `pi.skills` and is automatically discovered when the extension is installed. No manual copying needed.
  262. ### Component Gallery Reference
  263. The skill includes a reference library for 60 UI components with best practices, common layouts, and aliases. Each component links to [component.gallery](https://component.gallery) where the agent can browse real screenshots when needed.
  264. **Before:** "Show me collapse options" → agent might not connect that to accordion, or know what components are available for the use case.
  265. **After:** Agent has 60 components to suggest from. Knows *collapse = accordion = disclosure = expander*. Knows *Blueprint = dense, dark-native; Ant = clean, blue primary.* Can browse [100+ real implementations](https://component.gallery/components/accordion/) when it needs concrete references.
  266. The reference enables discovery (find/suggest components), cross-referencing (connect related terms), and design vocabulary (know what systems look like) — plus guidance on *when* to show distinct design systems vs variations of one style.
  267. A separate vocabulary lookup (`LOOKUP.md`) resolves ambiguous user terms to canonical components. When a user says "dropdown" (Select? Combobox? Dropdown menu?) or "popup" (Modal? Popover? Tooltip?) or describes intent ("I need something that expands"), the agent can consult the lookup to understand what they mean and ask the right clarifying questions when needed.
  268. ## Limitations
  269. - Only one deck can be active at a time. Complete or cancel before starting another.
  270. - Image blocks require absolute file paths on disk (no URLs).
  271. - The `summary` slide ID is reserved and cannot be used for custom slides.
  272. - Mermaid diagrams load from CDN — requires internet on first load.
  273. - macOS tested primarily; Linux and Windows support is best-effort.
  274. ## Credits
  275. UI component reference data sourced from [component.gallery](https://component.gallery) by Iain Bean.

Ratings and comments

Sign in to rate this skill.

Sign in

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