sideshow
The missing visual surface companion for agents - generate UI mockups, data visualizations, code explainers, and more
What is it?
What it is
A live visual surface for terminal coding agents that publishes multimodal content—diagrams, markdown, diffs, terminal output, images, etc.—and renders it live in a browser.
Why it exists
To let agents communicate ideas visually, combine multiple media types, reduce token usage by sending only content instead of full HTML, and work with any existing agent harness (Claude Code, Codex, Pi, etc.).
Who should use it
Developers and teams building or using terminal coding agents who want a live visual surface for agent output, such as those working with Claude Code, Codex, Pi, or other agent harnesses.
Who should avoid it
Users who do not use coding agents or prefer static documentation and are not comfortable setting up a Node server or integrating with agent instructions.
How it works
A quick walkthrough in plain English
How sideshow works
Step 1 of 3
You interact with it
Open sideshow, send a request, or connect it to your stack.
Features
Advantages
- Reduces token usage and costs for agents
- Speeds up rendering and reduces latency
- Provides clear visual representations of agent output
- Supports a wide range of surface types for richer communication
- Easy to integrate with existing agents via simple setup block
- Flexible deployment options (local or Cloudflare Workers)
- No need to ship full HTML/CSS/JS for each surface
- Built‑in viewer UI with sidebar and comment thread
- Open‑as‑image feature for documentation and sharing
- TypeScript code runs directly on Node, simplifying development
Disadvantages
- Requires Node 22.18 or newer
- Open‑as‑image PNG rendering only works on Cloudflare Workers (needs Browser Rendering binding)
- Local Node server lacks headless browser for PNG export (action disabled)
- Viewer is browser‑only; no native desktop or TUI support (aside from experimental sibling)
- Limited documentation for advanced integration tiers
- Potential learning curve for agents to publish surfaces correctly
Installation
cloud
See docs/deploying.md
native
npm install npx sideshow serve --open
FAQ
How do I set up sideshow for my agent?
Install via `npm install`, run `npx sideshow serve --open` to start the viewer, then paste the setup block from `http://localhost:8228/setup` into your agent's instructions to enable surface publishing.
Which agents are compatible with sideshow?
sideshow works with any agent harness supporting MCP or shell commands, including Claude Code (desktop/CLI), Codex, Opencode, Pi, and others. Full integration details are in [docs/connecting-agents.md](docs/connecting-agents.md).
What types of content can agents publish?
Agents can publish surfaces containing html (interactive UIs), markdown (prose/code), diff (code reviews), terminal (ANSI output), image (uploads), mermaid (diagrams), and json (collapsible trees), as shown in the [sideshow demo](docs/surfaces/).
How does sideshow reduce token usage?
Surfaces send only content data (e.g., mermaid text, JSON values) to the viewer, which renders it using pre-styled themes. This avoids shipping full HTML/CSS, saving ~40-90% tokens compared to standalone HTML documents.
Can I deploy sideshow on Cloudflare Workers?
Yes, sideshow supports Cloudflare Workers deployments for remote agent-viewer setups. This requires the Browser Rendering binding and enables features like 'open-as-image' screenshots.
What is the terminal surface mentioned in development?
The `sideshow-term/` branch is an alpha project rendering surfaces in a terminal user interface (TUI) instead of a browser, with unstable APIs for experimental use.
Featured in Videos
YouTube tutorials and walkthroughs for sideshow
Alternatives
Similar projects ranked by category, topics, and text overlap.
