modem-dev/sideshow: a live visual surface for terminal coding agents
The missing visual surface companion for agents - generate UI mockups, data visualizations, code explainers, and more
At a glance
- What is it?
- sideshow publishes diagrams, diffs, terminal output and sandboxed HTML from a coding agent into a browser viewer on localhost:8228. It is a rendering and comment surface, not an agent, and it assumes Node 22.18 or newer.
- Who is it for?
- Adopt sideshow if you already run a shell-capable agent and want its diagrams, diffs and HTML sketches rendered in a browser instead of pasted into a transcript. Skip it if you need a hosted multi-user review product or you cannot run Node 22.18 or newer locally.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap sideshow fills between an agent and its terminal
A terminal coding agent communicates in text. When it proposes an architecture, traces a request flow, or sketches a UI it is about to build, that proposal arrives as prose or as a fenced code block you have to reconstruct mentally. sideshow's answer is to give the agent a screen: the README describes it as "a live visual surface for your terminal coding agent," and the repository's own description calls it "the missing visual surface companion for agents."
The target user is narrow and specific. You already run a shell-capable agent such as Claude Code, Codex, Opencode, Pi or amp, and you are willing to run a local server alongside it. This is not a tool for someone who wants a hosted dashboard, and it is not an agent itself. It renders what another program publishes.
The README's stated motivations are three: seeing what the agent means rather than reading a description, combining surface types in one card, and spending fewer tokens because the viewer supplies the chrome. That last argument is the most concrete claim in the project, and it is a claim about the agent's output cost, not about runtime speed.
Surfaces, parts, and how a card reaches the browser
The unit of display is a surface, and according to the README a surface is "an ordered list of parts." One card can carry several parts, so a markdown rationale can sit stacked above the diff it explains. The documented part types are html, markdown, diff, terminal, trace, image, mermaid, json and code.
Each type has a defined rendering path. The html part is markup the agent authors and the viewer renders it sandboxed; the README states that shapes and buttons inside it can call sendPrompt() to post back into the thread. The diff part renders a patch natively as a syntax-highlighted review in unified or split layout. The terminal part shows monospace output with ANSI color inside a terminal-window frame. The trace part turns an agent run into an expandable step timeline. The image part is an uploaded, content-addressed asset drawn with a caption. The mermaid part converts diagram source to SVG in the sideshow palette, and nodes tagged with :::accent are highlighted. The json part renders a value as a collapsible tree. The code part is highlighted with shiki and numbered, and it accepts a starting line so an excerpt keeps its original line numbers.
The data flow is one-directional until you type. The agent publishes a surface to the server, the viewer renders it live in the browser, and comments you write under a card are read back by the agent, which can then publish a revised version. The README's demo description follows exactly that loop: a diagram appears, the user asks a question under it, and the agent revises the snippet and replies in the thread. The repository layout reflects this split, with separate server/, viewer/, mcp/, workers/, extensions/ and skills/ directories.
Installing sideshow and publishing your first surface
The README states the requirement plainly: Node 22.18 or newer. The quick start is two commands. The first installs dependencies in a checkout, and the second starts the viewer on port 8228 and opens it.
npm install
npx sideshow serve --open # viewer on http://localhost:8228After that, the agent needs to know the surface exists. The README's handoff is a single curl that appends a bootstrap block to your agent instructions file. That block tells any agent with a shell to fetch current instructions from the running server, then publish surfaces and read your comments.
curl -s http://localhost:8228/setup >> AGENTS.mdWith that in place, asking the agent to "sketch this on sideshow" should produce a card in the viewer. The README notes the same handoff is available inside the running viewer: the sidebar footer has an agent setup link and a connect agent screen, which is where you copy the MCP command without leaving the browser. If you have no agent configured yet, the demo command seeds two example sessions so you can inspect the rendering before wiring anything up.
npx sideshow demoRicher integration tiers (CLI, MCP, the Pi extension, and the Claude Code skill plus plugin) live in docs/connecting-agents.md rather than in the quick start, so the setup block is the shallow end and the MCP path is the deeper one.
Where sideshow stops being the right tool
The sandboxed html part is the most capable and the most constrained piece at the same time. The README says the markup renders sandboxed, which is the correct default when the author is a language model, but it also means anything you write that depends on same-origin access, external network calls, or a persistent page context is not going to behave like a page you opened yourself. Treat an html part as a sketch, not as a deployed artifact.
There is a harder boundary around persistence and collaboration. The README describes a local viewer on localhost:8228, sessions in a sidebar, and comment threads between you and the agent. It does not document a hosted mode, user accounts, or a shared review workflow, and the README does not document rollback of a published surface. If your actual need is a review tool where several people comment on a shared link, this is the wrong shape of product.
Token economics also deserves a caveat. The README's argument is that a standalone HTML document re-sends its whole design system while a surface sends only content, so a surface costs fewer tokens and draws faster. That comparison depends on what the agent was going to emit otherwise. For a short markdown note, publishing a surface adds a round trip and a tool call for very little visual gain. The saving is real for large HTML explainers and marginal for small text.
Finally, the project is moving. Releases v0.12.0, v0.13.0 and v0.14.0 landed on 2026-07-26, 2026-08-11 and 2026-09-07, and the last push to main was on 2026-09-07. A pre-1.0 version number on a fast cadence means the surface API and the setup block can change between versions, so pin the version you install if you script the handoff.
sideshow against a plain HTML preview or a hosted artifact tool
The obvious alternative is having the agent write a standalone HTML file and opening it in a browser tab. The difference is architectural rather than cosmetic. A standalone file is self-contained: it carries its own doctype, reset, palette and typography, and the agent pays tokens for all of it every time. sideshow inverts that. The viewer owns the chrome and the theme, the agent sends content, and the README's token economics section frames the whole design around that split. The second difference is the loop. A file on disk is a dead end until you reopen it; a surface is addressable, versioned by republication, and carries a comment thread the agent can read. If you only need to look at a page once, the file is simpler and has no server. If you want the agent to react to what you said about the page, the file cannot do it.
The other comparison worth drawing is against a hosted artifact or preview service. Those give you a URL you can send to a colleague, which sideshow's documentation does not describe. They also put your content on someone else's infrastructure, which sideshow avoids by running locally. The trade is collaboration for locality. Pick based on whether the reviewer is you or a group.
Licence, maintenance and the cost of keeping up
sideshow is MIT licensed, and package.json declares "license": "MIT" with publishConfig access set to public on npm. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a summary of the licence family, not legal advice for your situation; read the LICENSE file in the repository before you ship anything derived from it.
The maintenance picture is current. The repository is not archived, the last push was on 2026-09-07, and the three most recent releases are v0.12.0 on 2026-07-26, v0.13.0 on 2026-08-11 and v0.14.0 on 2026-09-07. A .changeset/ directory at the repository root indicates the project uses changesets for versioning, so each release has a recorded changelog entry rather than an ad hoc tag.
The upgrade cost is the part to plan for. The package exposes several subpath exports, including ./server, ./app, ./workers, ./viewer, ./viewer-embed and ./theme-tokens. If you embed the viewer or import the server module rather than just running the CLI, a minor version bump can move those entry points. The setup block your agent fetches from /setup is served by the running instance, which means an upgrade changes agent behaviour without any change on your side. Pin the version in package.json and re-run the setup curl after each bump.
Editorial conclusion
Adopt sideshow if you already run a shell-capable agent and want its diagrams, diffs and HTML sketches rendered in a browser instead of pasted into a transcript. Skip it if you need a hosted multi-user review product or you cannot run Node 22.18 or newer locally. Before committing, run npx sideshow demo, then check that curl -s http://localhost:8228/setup appends instructions your specific harness actually follows.
Frequently asked questions
What is sideshow?
sideshow is a live visual surface for terminal coding agents. It publishes surfaces such as diagrams, UI sketches, rendered markdown, diffs, terminal output and images, and renders them in your browser while the agent works.
What does sideshow mean?
In this project the name refers to a visual surface published by a coding agent and rendered live in a browser viewer, described in the README as a live visual surface for your terminal coding agent.
Is sideshow a legit site?
sideshow is an MIT-licensed open source project published on npm as the sideshow package, with the source at github.com/modem-dev/sideshow and a homepage at sideshow.sh. The viewer runs locally on port 8228 rather than as a hosted service.
How do I use sideshow points?
The README documents no points or rewards system. The closest documented flow is the comment thread: you type a question under a published card and the agent reads it and replies in the thread.
Community notes