mockpit

A design-decision loop for terminal coding agents.

Your agent publishes a mock (a page or a component) in each of its UI states and in a few parallel variants. It shows up live in your browser with the agent's questions beside it: pick a variant from pictures, tune the knobs it exposed, leave comments on the parts it declared, then press Send, at your own pace. Nothing the agent calls waits for you: it gets the whole batch once and revises.

Fork of sideshow

mockpit is a fork of sideshow by Ben Vinegar, sponsored by Modem. The renderer, sandboxing, MCP/CLI/HTTP tiers and Cloudflare deploy all come from that work. Thank you.

Upstream is a live visual surface where agents post renders and you comment. mockpit turns that into a design-decision loop:

The loop

1. Publish. The agent publishes each state of the mock ("Writing", "Lab open") in one or more variants ("quiet", "dark"). One stage shows the mock, one state at a time.
2. Ask. The agent asks what it can't decide alone: which variant, where a panel goes, which of two layouts. The question lives in the mock, not in chat; the agent tells you where to look and ends its turn. Options bound to a variant or to knob values render as pictures; hovering one previews it on the stage, clicking picks it, and the part it changed is outlined. A region the agent drew several ways (a part with fills: one data-part, a data-fill per alternative) is asked about once; a part inside a fill is asked only while that fill is chosen. Variants the agent forgot to ask about get a built-in Which variant?.
3. Tune. Parts the agent declared are selectable on the stage. Tune lists them with the knobs it declared for each, a Borrow line for a part another variant draws differently, plus a comment field. Presets save a set of tuned values in your browser.
4. Send. Everything above is a draft (it survives a reload) until one Send. A mock with a single variant and no questions gets Use this / Revise instead. The Send lands in the Thread as Not seen yet, then Delivered once the agent has it. If it isn't picked up, tell your agent you've answered.
5. Revise. The agent gets one reply (answers, tuned values, borrowed parts, comments) on its next write, its next feedback call, or from mockpit watch under a background monitor. It publishes the next version. Versions are named by their variant's own number ("Dark #2"); the version bar walks the history, and Use this puts an older one back in use. Variants that lost are archived, not deleted.

Home lists the project's mocks with a thumbnail, their states and how many questions are open, with "Answer next ›" to jump to the first one. Dark and light themes, toggled from the top bar. On a phone or an iPad in portrait the design is a canvas you pan and pinch, at each width the agent names (or one you pick: Phone 390, Tablet 744, Desktop 820, Wide 1280) side by side, and the questions float over it in a card you can snap to a corner, a side or the bottom, or tuck against an edge. On a desktop, Inspect opens the stage full screen to pan and pinch-zoom it.

Quick start

Requires Node 22.18 or newer.

git clone https://github.com/fabiogaliano/mockpit && cd mockpit
npm install
npm start                      # viewer on http://localhost:8228
npm link                       # puts the `mockpit` CLI on your PATH

Point your agent at it by pasting the setup block into its instructions:

curl -s http://localhost:8228/setup >> AGENTS.md

Then run mockpit init once per repo and ask the agent to "mock this up on mockpit". No agent handy? mockpit demo seeds the Writer: one mock in four states and three variants, with questions, knobs and declared parts.

MCP, the Pi extension and the Claude Code plugin are covered in docs/connecting-agents.md.

What a mock can show

A version is an ordered list of surfaces, and one version can carry several. Html is what design mocks use and the only kind with parts and knobs; the others render the same way on the stage.

There are also terminal (ANSI output), image (uploaded assets), json (collapsible tree) and code (shiki-highlighted source with line numbers).

Agent verbs

Ten verbs, the same on every tier with the same fields: a zero-dependency CLI for agents with only a shell, MCP over stdio or streamable HTTP at /mcp, and plain HTTP. None of them waits for the user.

The CLI adds mockpit init (detect the repo's design system, once per repo) and mockpit watch (one line per Send, for a background monitor).

• publish is the one write. It creates the mock, state or variant, or the next version of an existing one. Send html, the full ordered surfaces list (an entry that is only {id} keeps that surface), or parts to replace just the declared elements.
• feedback returns at once with what the user sent since the agent last heard, plus pending: whether each mock is open in the viewer and how far the user's draft has got (2 of 3 answered). Every write returns feedback too, and each Send is delivered exactly once across all of them.
• Questions are nudged. A publish that leaves several variants with no question binding them returns a nudge and a ready suggestedAsk.

A typical turn:

mockpit publish --mock writer --state "Writing" --variant quiet --html quiet.html
mockpit publish --mock writer --state "Writing" --variant dark  --html dark.html
mockpit ask     --mock writer "Quiet or dark?" --option Quiet=quiet --option Dark=dark
# the agent says where to look and ends its turn; once you've answered:
mockpit feedback

The running server serves the brief at /agent-howto: one short, project-aware document an agent reads before its first publish. Reference topics (knobs, asks, surfaces, html, feedback, http, scripts) are at /agent-howto?topic=<id>; /guide is the html topic. run executes one script against the same verbs on the server, so publishing variants and asking take one call; /mcp?mode=code serves it as the only tool, for connectors without a codemode of their own.

Guidance

Agents read one brief before their first publish, in layers. Higher wins:

A rules file has ## Rules (always followed) and ## Suggestions (aimed for), and turns packs on with packs: [design-craft] in its frontmatter. mockpit rules sends the project's file to the server; mockpit init does it too. examples/rules.md is the maintainer's own, symlinked to ~/.mockpit/rules.md.

Run it anywhere

It runs locally as a small Node server (SQLite at ~/.mockpit/mockpit.db), or on Cloudflare Workers when your agent and browser are on different machines. See docs/deploying.md.

The server keeps an event log, one JSON line per agent call, viewer write and live-feed connection (ids and shapes, never content), at ~/.mockpit/events.jsonl next to the database. It rolls over at 10 MB. Set MOCKPIT_LOG to another path, or to off to disable it; on Workers it goes to Workers Logs. node scripts/inspect.ts in a checkout reads it alongside the database and Claude Code transcripts.

The server app is importable from mockpit/server (createApp, SqlStore, createSqliteStorage). The embeddable viewer engine (mockpit/viewer-embed, mountViewer) is gone: the viewer is self-hosted only.

Migrating from 0.x

• SQLite workspaces migrate in place on first boot. Each item becomes a single-state mock with its variants and version history; comments keep their ids and sequence numbers, so agents' feedback cursors carry over. Comments a user was still drafting become the mock's draft. Deployed Durable Objects migrate the same way.
• The JSON store is gone. If you run with MOCKPIT_STORE=json, start your current version once without it before upgrading: env -u MOCKPIT_STORE mockpit serve (keep MOCKPIT_DATA/MOCKPIT_DB if you set them). That first SQLite boot copies ~/.mockpit/mockpit.json into ~/.mockpit/mockpit.db, as long as the database is still empty; then upgrade. The JSON file is left untouched either way.
• --item is now --mock (mockpit publish --mock <slug> --state <s> --variant <v>), and the MCP tools are named by verb (publish, ask, read, feedback, say, export, upload, guide).
• Removed: the item, post, snippet and session-page routes (/api/projects/:name/items, /api/posts, /api/surfaces, /api/snippets, /session/:id, /p/:id), ?part=, the item/post MCP tools and their deprecated aliases (publish_item, publish_post, publish_surface, …), the CLI's page, list, sessions, update, per-kind shortcuts (markdown, diff, …), test-post and trace* commands, the github/gruvbox/one themes and the embed engine. Agents should re-fetch /agent-howto; refresh pasted setup blocks from /setup.

Development

npm run dev          # server with watch + viewer watch build
npm run typecheck    # node + workers + viewer
npm run lint         # oxlint
npm run format       # oxfmt

The architecture and contributor rules are in AGENTS.md.

License

MIT. The original sideshow copyright is retained.