How to get diagrams and mockups out of a terminal coding agent

Ask a terminal coding agent to propose an architecture, sketch two directions for a dashboard, or show you the shape of an API response, and you get the same thing every time: a wall of text describing something inherently visual. The agent is not being obtuse. It has one output device, and that device prints characters.

The questions do not go away because the medium is wrong. "Which of these two layouts?" and "walk me through this data flow" are exactly the moments where you steer an agent, and steering through prose descriptions of pictures is slow and error-prone. Teams work around it three ways, none of them great, which is why we eventually built a fourth. That tool, Sideshow, comes up in the second half; disclosure now: it is built by our team at Modem, the open-source core is MIT-licensed, and it runs locally with no account.

The workarounds, honestly assessed

ASCII art. The agent draws boxes and arrows in the terminal. Zero setup, works everywhere, and for a three-node diagram it is genuinely fine. Past that it degrades fast: alignment breaks under wrapping, wide diagrams overflow the pane, and there is no fidelity at all for UI questions, where "what does it look like" is the entire question.

The screenshot round-trip. The agent writes HTML, drives a headless browser to render it, saves a PNG, and you open the file. This produces real fidelity and we have used it plenty. But it is a one-way pipe with a long turn: every iteration is a full rewrite-render-save-open cycle, the output is a dead image you cannot click, and your feedback travels back by you describing what is wrong in text, which is the original problem again.

Temp HTML files. The agent writes dashboard-v2.html somewhere and you open it in a browser. Faster than screenshots and the output is live, but the files scatter, each one ships its own ad-hoc styling, you refresh manually to see revisions, and the agent has no idea what you looked at or what you thought. There is no channel back.

The shared defect is the missing return path. All three get pixels in front of you eventually; none of them get your reaction back to the agent as anything other than more prose in the chat.

Give the agent a render target

Sideshow's model: a small local server with a browser viewer, and the agent publishes to it from the terminal while it works. Published cards render live, so the diagram appears as the agent thinks, not after a save-open cycle.

The agent is not limited to hand-writing HTML, either. A surface is composed of typed parts the viewer knows how to render: mermaid source becomes a themed SVG diagram, a patch becomes a syntax-highlighted diff, a JSON value becomes a collapsible tree, plus markdown, code, terminal, image, and sandboxed html for actual UI mockups. That matters beyond looks: the project's measurements show handing over mermaid source instead of a hand-drawn SVG cuts the agent's output tokens by roughly 90%, which also means the drawing appears sooner.

Parts compose, so one card can carry a markdown rationale above the diff it explains, or two HTML mockups side by side with a "which direction?" underneath.

The half that matters: comments come back

The viewer is not read-only. Each card has a comment thread, and comments are delivered to the agent: it can block on sideshow wait (or the wait_for_feedback MCP tool) until you react, then revise the card or reply in the thread. Delivery is exactly-once, so feedback is not lost or double-processed.

That closes the loop the workarounds leave open. "Move the nav to the left and drop the third chart" typed under the mockup reaches the agent as structured feedback about that card, and the revised card appears where the old one was. This is the difference between an export format and a working surface: you are steering, not narrating.

Local, remote, or hosted

The core runs locally: a small Node server (Node 22.18+), your machine, no account. When the agent and your browser are different machines, or you want the viewer on your phone, the same app deploys to Cloudflare Workers behind a token you set. There is also a hosted option at sideshow.sh with team boards and shared activity, free to start, if you would rather not run anything; the honest trade is that share links and rendered-PNG export need a reachable deployment, so a localhost-only board keeps its output to you.

Setup

npx sideshow serve --open    # viewer at http://localhost:8228

Connect whichever way your agent supports. Any agent with a shell can use the CLI directly; the running server serves a setup block that teaches it:

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

MCP-capable agents get tools (publish_post, update_post, wait_for_feedback, reply_to_user) plus usage instructions automatically:

claude mcp add --scope user sideshow -- npx -y sideshow mcp

Then ask for something visual: "sketch the two dashboard layouts on sideshow." The card appears in the viewer, you comment, the agent revises. No agent handy? npx sideshow demo seeds example sessions to look around.

If you are evaluating this category more broadly, output surfaces versus the browser-automation MCPs, see MCP servers that give coding agents a UI. Sideshow exists because we steer coding agents all day at Modem and got tired of reading descriptions of pictures; it stays MIT, local-first, and free.