A live visual surface for your terminal coding agent.
Your agent works in a wall of text; Sideshow gives it a screen. It publishes surfaces — diagrams, UI sketches, rendered markdown, syntax-highlighted diffs, terminal output, images — and they render live in your browser while it works.
| | |
See what your agent means. An architecture it's proposing, a flow it's tracing, a UI it's about to build — shown, not described in a paragraph you have to picture in your head.Multimodal. Combine diffs with mermaid diagrams, terminal output with HTML explainers, and more. Combine surfaces to illustrate ideas better.Faster, and fewer tokens. A standalone HTML document re-sends its whole design system every time; a surface sends only the content and the viewer supplies the chrome — far fewer tokens, and a faster draw. SeeToken economics.Works with the agent you already use. Works with any agent harness: Claude Code (desktop or CLI), Codex (desktop or CLI), Opencode, Pi, etc.
Requires Node 22.18 or newer.
npm install
npx sideshow serve --open # viewer on http://localhost:8228
Then point your agent at the surface — paste the setup block into its instructions:
curl -s http://localhost:8228/setup >> AGENTS.md
That bootstrap tells any agent with a shell (Pi, opencode, amp, codex, Claude Code) to fetch the current instructions from the running server, then publish surfaces and read your comments. Ask it to "sketch this on sideshow" and watch the card appear.
The running viewer has the same handoff built in: its sidebar footer carries an agent setup link (the block above) and a polished connect agent screen, so you can grab the right MCP command without leaving the browser.
No agent handy? npx sideshow demo
seeds two example sessions to look around.
Going further: richer integration tiers (CLI, MCP, the Pi extension, and the Claude Code skill + plugin) are in ** docs/connecting-agents.md**.
Every card below is real — published over the API and captured straight from the viewer. A surface is an ordered list of parts; one card can carry several.
Showing something visually costs tokens — the ones your agent spends writing it. A standalone HTML document pays for its whole design system (doctype, reset, palette, typography, component CSS, often a little JS) on every render. A surface pays for none of it: it hands the content over as data — mermaid source, a JSON value, a markdown table, a diff patch — and the viewer supplies the theme. Fewer output tokens also means a faster draw, since a model writes them one at a time.
Measured both ways on identical content (output tokens):
| Showing… | Hand-built HTML | sideshow surface | Saved |
|---|---|---|---|
| Architecture diagram | hand-drawn SVG | mermaid source | ~90% |
| API response | tree markup + JS | json surface | ~88% |
| Data table | table + CSS | markdown table | ~83% |
| Interactive UI mockup | standalone document | themed html fragment | ~42% |
Even an HTML surface you author inherits the viewer's theme tokens and pre-styled controls instead of shipping its own, so it still comes out ahead.
sideshow runs locally as a small Node server, or on Cloudflare Workers when your agent and your browser live on different machines (or you want the viewer on your phone). See ** docs/deploying.md**.
Each surface has an open-as-image action in its footer that renders the
surface to a PNG (/p/:id.png
) — handy for pasting into a doc or a chat. The image is captured by a headless browser, so it needs Cloudflare's Browser Rendering binding and only works on a Workers deployment. On the local Node server there is no headless browser, so the action is shown but disabled.
— every integration tier in detail: CLI, MCP, Pi, plain HTTP, and the Claude Code skill + plugin.Connecting agents— run a shared, tokened instance.Deploying to Cloudflare— architecture and contributor guide.AGENTS.mdTerminal surface (alpha). is an early sibling that renders to a TUI instead of the browser. APIs are unstable.sideshow-term/
npm run dev # server with watch + viewer watch build
npm test # node --test (unit/API + store contract)
npm run typecheck # three tsc programs: node + workers + viewer
npm run lint # oxlint
npm run format # oxfmt
The server and CLI have no build step — TypeScript runs directly on Node via
native type-stripping, and the npm package ships compiled JS built on prepack.
The viewer (viewer/src/
, Solid) is Vite-built into a single self-contained
viewer/dist/index.html
(npm run build:viewer
). See AGENTS.md for the full architecture and rules.
Sponsored by Modem.