sideshow

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.

Why

• 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. See Token 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.

Quick start

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 Connect Claude Code button, so you can grab it 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.

What your agent can show

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.

Token economics

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.

Run it anywhere

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.

Docs

• Connecting agents — every integration tier in detail: CLI, MCP, Pi, plain HTTP, and the Claude Code skill + plugin.
• Deploying to Cloudflare — run a shared, tokened instance.
• AGENTS.md — architecture and contributor guide.
• Terminal surface (alpha). sideshow-term/ is an early sibling that renders to a TUI instead of the browser. APIs are unstable.

Development

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.

Sponsor

Sponsored by Modem.

License

MIT