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 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.
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):
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 card's footer carries a share menu for taking a post elsewhere: copy its
link, copy the whole post as markdown (/api/posts/:id/markdown — prose stays
prose, code/diffs/terminal output/JSON/mermaid become fenced blocks, and an html
surface links back rather than pasting its markup), open it in a new tab, or open
it as an image.
That last one 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 unit/API/store tests + viewer unit tests
npm run coverage # separate all-source Node and viewer-TS coverage reports
npm run test:worker # real local workerd + Durable Object integration
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). Coverage is reported separately
for Node/Pi code and viewer unit tests rather than combining incompatible runtimes;
the Worker entrypoint is exercised in workerd and browser behavior in Playwright,
neither of which is folded into a misleading Node percentage. See
AGENTS.md for the full architecture and rules.
Sponsor
Sponsored by Modem.
