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. You comment back, and your comments reach the agent. Publish, render, comment, revise: a two-way loop, right next to the conversation.

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.
• Faster, and fewer tokens. sideshow surfaces are optimized for LLMs, so the agent produces higher-fidelity diagrams and visualizations faster and using fewer tokens.
• Comment instead of re-prompting. Click a card, leave a note. The agent reads it and revises — no copy-pasting screenshots or re-describing what you meant.
• Works with the agent you already use. Any agent with a shell can drive it over curl; richer tiers exist for CLI, MCP, Pi, and Claude Code.

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.

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.

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.

License

MIT