Skip to content
Back to search

protodeck

Design with Agents, 100% local

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ssebastianoo--protodeck/badge.svg)](/listings/ssebastianoo--protodeck)

HTML

<a href="/listings/ssebastianoo--protodeck"><img src="/api/listings/ssebastianoo--protodeck/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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 · 128 lines
  1. <img src="assets/logo.svg" alt="" width="72" height="72">
  2. # protodeck
  3. A prototype server for coding agents. Your agent writes plain HTML screens in a `protodeck/` folder, outside the app code. protodeck serves them with Tailwind, components and live reload, shows every screen side by side in MacBook, iPhone and Samsung frames, and adds a chat bar that sends your instructions back to the agent.
  4. ```
  5. npx protodeck init # starter protodeck/ folder + agent skill
  6. npx protodeck # serve it at http://127.0.0.1:4321/
  7. ```
  8. `bunx protodeck` works the same way. The package has no runtime dependencies. Tailwind v4 and the Inter font ship inside it, so everything works offline.
  9. ## Folder structure
  10. ```
  11. protodeck/
  12. home/index.html one folder per screen
  13. login/index.html
  14. checkout/index.html
  15. components/button.html one file per component, used as <x-button>
  16. theme.css optional Tailwind v4 @theme tokens
  17. ```
  18. Every HTML file gets Tailwind, a base reset, the Inter font and the live reload script injected into its `<head>`, so a screen can be just its body markup.
  19. ## Components
  20. `components/card.html`:
  21. ```html
  22. <div class="rounded-2xl p-6 shadow {{class}}">
  23. <h2 class="font-semibold">{{title | Untitled}}</h2>
  24. <slot></slot>
  25. </div>
  26. ```
  27. Use it in a screen as `<x-card title="Plan">…</x-card>` or `<x-card />`. Attributes fill `{{name}}` (with an optional `| fallback`), and children go into `<slot></slot>`. Components can use other components.
  28. ## Gallery
  29. - **Move around:** scroll or swipe with two fingers to pan, drag the background, or hold Space and drag. Arrow keys pan too (Shift for bigger steps). The canvas has no edges; Shift+1 jumps back to the screens.
  30. - **Zoom:** pinch, Ctrl/⌘ + scroll, ⌘ + `+`/`-`, or the slider. ⌘ + `0` resets.
  31. - **Devices:** pick frames from the Devices menu, or add your own width and height with "Add custom size…". Custom sizes are saved in the browser.
  32. - **View:** show or hide the components section (hidden by default) and switch between same-height and true relative frame sizes.
  33. - **Export:** the Export button at the top right saves screens as PNG images (one per route and device, at 1×–3×, optionally full page height) or as self-contained HTML pages (one per route, with the compiled CSS, font and images inlined). Routes and devices start from what the canvas shows. Several files are saved as one .zip.
  34. - **Light and dark:** the button at the top right switches the gallery and the previews. Screens follow it through Tailwind's `dark:` variant (a `data-protodeck-theme` attribute on `<html>`). Screens that use `dark:` classes also get the native dark color scheme for form controls and scrollbars.
  35. ## Chat bar
  36. The bar at the bottom of the gallery sends an instruction to your agent along with:
  37. - the current screen and device frame (click a frame to choose them)
  38. - the selected element's selector, HTML and the component it comes from (use the picker button, then click an element in any frame)
  39. The agent edits the files in `protodeck/` and the frames reload by themselves. Everything runs locally: the server spawns the agent in the folder that contains `protodeck/`.
  40. Pick the agent, model and reasoning level from the selector in the bar. It lists every installed agent: Claude Code (Default, Opus, Sonnet, Haiku, Fable, passed as `--model` and `--effort`) and Codex (the models in its local cache, passed as `--model` and `model_reasoning_effort`). "Default" leaves the agent's own setting alone. Use **+** to start a new conversation. Switching to a different agent also starts one.
  41. | `--agent` | What runs |
  42. | --- | --- |
  43. | `claude` (default if installed) | `claude -p … --output-format stream-json --permission-mode acceptEdits`. The conversation continues until you start a new chat. |
  44. | `codex` | `codex exec --json --full-auto …`. Each instruction starts a fresh run. |
  45. | `"cmd … {prompt}"` | Any CLI, listed first in the selector. `{prompt}` is replaced with the full prompt (it is appended if missing). Its stdout is shown as text. |
  46. | `none` | Gallery only. |
  47. `--agent` sets which agent is selected by default.
  48. Pass extra flags with `--agent-args "--max-turns 20"`.
  49. ### Providers: more accounts
  50. Use the gear at the bottom of the agent list to add a provider: another Claude Code or Codex account, kept in its own config folder. For example, a "Work" provider with `~/.claude-work` runs `claude` with `CLAUDE_CONFIG_DIR=~/.claude-work`, and Codex providers get `CODEX_HOME`. Sign in to the account once from a terminal with `CLAUDE_CONFIG_DIR=~/.claude-work claude` or `CODEX_HOME=~/.codex-work codex login`. Providers show up in the selector next to the default agents, marked with their first letter.
  51. The first time you add one, protodeck asks where to save it:
  52. | Scope | File |
  53. | --- | --- |
  54. | This project | `.protodeck/config.json` next to the `protodeck/` folder |
  55. | Global | `~/.protodeck/config.json` (`%USERPROFILE%\.protodeck\config.json` on Windows) |
  56. protodeck reads the project file first and falls back to the global one only when the project has none. The file is reread on every page load and message, so you or your agent can edit it by hand while the server runs:
  57. ```json
  58. {
  59. "providers": [
  60. { "name": "Work", "agent": "claude", "configDir": "~/.claude-work" },
  61. { "name": "Side", "agent": "codex", "configDir": "~/.codex-side" }
  62. ]
  63. }
  64. ```
  65. `agent` is `claude` or `codex`. `configDir` accepts `~`, and relative paths resolve against the project (or the home folder for the global file). The project file holds personal paths, so you may want to add `.protodeck/` to `.gitignore`.
  66. ## CLI
  67. ```
  68. protodeck [dir] Serve the prototype folder (default ./protodeck)
  69. protodeck init [dir] Create a starter prototype and install the skill
  70. protodeck skill [--global] Install the skill into .claude/skills and .agents/skills
  71. protodeck kill [port] Stop servers left running in the background (all, or the one on [port])
  72. -p, --port <n> default 4321 (the next free port is used if it is taken)
  73. --host <host> default 127.0.0.1
  74. -a, --agent <agent> claude | codex | none | "<command> {prompt}"
  75. --agent-args <args> extra args for claude/codex
  76. -o, --open open the browser
  77. ```
  78. If an agent started the server in the background and it is still running, `protodeck kill` stops it. Pass a port to stop only that one.
  79. ## The skill
  80. `skill/SKILL.md` tells the agent to build prototypes as HTML in `protodeck/`, to treat Tailwind and components as already available, and to start the server with `npx protodeck`. `protodeck init` and `protodeck skill` copy it into the project.
  81. ## Development
  82. ```
  83. npm install
  84. npm run build # embeds assets, compiles TypeScript to dist/
  85. npm test
  86. npm run build:bin # standalone binary with Bun (bin/protodeck), for machines without Node
  87. ```
  88. `scripts/gen-assets.mjs` embeds Tailwind, the font, the UI files in `ui/`, the skill and the templates into one generated module. That lets the npm build and the Bun binary share the same code, without reading any files at runtime.
  89. ## Security
  90. The server binds to 127.0.0.1, rejects requests whose `Host` is not local (to block DNS rebinding), and the chat endpoints require a per-session token that is embedded in the gallery page. Other websites therefore cannot trigger your agent.

Ratings and comments

Sign in to rate this skill.

Sign in

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