{"id":50797806,"url":"https://github.com/modem-dev/sideshow","last_synced_at":"2026-06-17T21:01:01.964Z","repository":{"id":364293090,"uuid":"1265774025","full_name":"modem-dev/sideshow","owner":"modem-dev","description":"A live visual surface for terminal coding agents — agents draw HTML snippets, you watch and comment back","archived":false,"fork":false,"pushed_at":"2026-06-16T19:34:15.000Z","size":2050,"stargazers_count":71,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T20:28:10.965Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modem-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-11T04:22:55.000Z","updated_at":"2026-06-16T19:58:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/modem-dev/sideshow","commit_stats":null,"previous_names":["modem-dev/sideshow"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/modem-dev/sideshow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fsideshow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fsideshow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fsideshow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fsideshow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modem-dev","download_url":"https://codeload.github.com/modem-dev/sideshow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modem-dev%2Fsideshow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34465322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-12T16:01:34.083Z","updated_at":"2026-06-17T21:01:01.922Z","avatar_url":"https://github.com/modem-dev.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# sideshow\n\n[![CI](https://github.com/modem-dev/sideshow/actions/workflows/ci.yml/badge.svg)](https://github.com/modem-dev/sideshow/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA live visual surface for terminal coding agents.\n\nCoding agents work in plain text, but a lot of what they have to say is\nvisual: an architecture diagram, a UI sketch, a chart. sideshow runs a small\nserver with a browser viewer. Agents publish HTML snippets to it from the\nterminal, the snippets render live, and you can comment on them in the\nbrowser. Comments are delivered back to the agent.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/sideshow-dark.png\"\u003e\n  \u003cimg alt=\"The sideshow viewer: agent sessions in a sidebar, a published JWT-flow diagram with a comment thread between the user and claude-code, and an interactive backoff explainer below\" src=\"docs/sideshow-light.png\"\u003e\n\u003c/picture\u003e\n\nAbove: an agent published a sequence diagram while working on an auth\nrefactor. The user asked a question under it, and the agent answered in the\nthread and revised the snippet.\n\nThe loop in motion — publish, live appear, comment, revise:\n\n![Animated demo: an agent publishes a diagram that appears live in the viewer, the user types a question under it, and the agent revises the snippet to a second version and replies in the thread](docs/sideshow-demo.gif)\n\n## Quick start\n\nRequires Node 22.18 or newer.\n\n```sh\nnpm install\nnpx sideshow serve --open   # viewer on http://localhost:4242\n```\n\nThen tell your agent the surface exists:\n\n```sh\ncurl -s http://localhost:4242/setup \u003e\u003e AGENTS.md\n```\n\nThat block teaches any agent with a shell tool (pi, opencode, amp, codex,\nClaude Code) how to publish snippets and poll for your comments using curl.\n\nNo agent handy? `npx sideshow demo` seeds two example sessions so you can\nlook around the viewer.\n\n## Connecting agents\n\nUse whichever the agent supports:\n\n1. Shell. The `sideshow` CLI has no dependencies and handles session grouping\n   itself:\n\n   ```sh\n   sideshow publish sketch.html --title \"Cache layout\"\n   sideshow wait      # block until the user comments\n   ```\n\n2. MCP. Tools: `publish_snippet`, `update_snippet`, `wait_for_feedback`,\n   `reply_to_user`, `list_snippets`, `get_design_guide`. Available over stdio\n   or directly from the server at `/mcp`:\n\n   ```sh\n   claude mcp add --scope user sideshow -- npx -y sideshow mcp\n   # or, no local process:\n   claude mcp add --scope user --transport http sideshow http://localhost:4242/mcp\n   ```\n\n3. Plain HTTP. `POST /api/snippets`, `PUT /api/snippets/:id`, and\n   `GET /api/comments?wait=60` for long-polling. Documented at `/guide`.\n\nAgents that connect over MCP get usage instructions automatically. For\neverything else there is the `/setup` block above, and Claude Code users can\noptionally install the skill in `skills/sideshow/`\n(`cp -r skills/sideshow ~/.claude/skills/`), which adds workflow guidance for\nillustration requests.\n\n## Concepts\n\nA session is one agent conversation. Sessions appear in the viewer sidebar;\nclick a title to rename, hover to delete.\n\nA snippet is one published HTML fragment. It renders in a sandboxed iframe\n(`sandbox=\"allow-scripts\"`, no same-origin) with a CSP that limits external\nresources to a short CDN allowlist. Updating a snippet creates a new version,\nand old versions stay viewable.\n\nEach snippet has a comment thread. You write in the browser; agents read via\nlong-poll (`sideshow wait` or the `wait_for_feedback` tool) and can reply.\nA snippet can also call `sendPrompt('...')` to post to its own thread.\n\nThe design contract at `/guide` tells agents how to write snippets that fit\nthe viewer: fragment-only HTML, theme CSS variables, dark mode rules.\n\n## Architecture\n\n- `server/app.ts` — runtime-agnostic Hono app: REST API, SSE live feed,\n  long-poll comments, snippet renderer, MCP endpoint.\n- `server/storage.ts` — `Store` interface and the JSON-file implementation.\n- `viewer/` — the viewer, a single static HTML file.\n- `bin/sideshow.js` — CLI, Node built-ins only.\n- `mcp/server.ts` — stdio MCP server, a thin client over the HTTP API.\n- `workers/` — Cloudflare entry point and SQLite store.\n\n## Deploying to Cloudflare\n\nThe same app runs on Cloudflare Workers, which is useful when agents run on\nmachines other than the one with the browser, or when you want the viewer on\nyour phone.\n\n```sh\nnpx wrangler login\nnpx wrangler secret put SIDESHOW_TOKEN   # any long random string\nnpm run deploy                           # https://sideshow.\u003caccount\u003e.workers.dev\n```\n\nA deployed instance requires the token on every request. Open the viewer once\nas `/?key=\u003ctoken\u003e` to set a cookie. Agents need two environment variables, and\nthe CLI and stdio MCP pick them up automatically:\n\n```sh\nexport SIDESHOW_URL=https://sideshow.\u003caccount\u003e.workers.dev\nexport SIDESHOW_TOKEN=\u003ctoken\u003e\n```\n\nRemote agents can also connect MCP straight to the deployment:\n\n```sh\nclaude mcp add --transport http sideshow https://sideshow.\u003caccount\u003e.workers.dev/mcp \\\n  --header \"Authorization: Bearer $SIDESHOW_TOKEN\"\n```\n\nImplementation: the whole app runs inside a single Durable Object with\nSQLite storage. One instance per board keeps the in-memory event bus\nauthoritative, so SSE and long-polling behave the same as the local server.\n\n## Development\n\n```sh\nnpm run dev          # server with watch + viewer watch build\nnpm test             # node --test\nnpm run typecheck    # tsc --noEmit\nnpm run lint         # oxlint\nnpm run format       # oxfmt\n```\n\nThe server and CLI have no build step — TypeScript runs directly on Node via\nnative type-stripping, and the npm package ships compiled JS built on prepack.\nThe viewer (`viewer/src/`, Solid) is the exception: Vite builds it into a\nsingle self-contained `viewer/dist/index.html` (`npm run build:viewer`). See\n[AGENTS.md](AGENTS.md) for architecture rules.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodem-dev%2Fsideshow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodem-dev%2Fsideshow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodem-dev%2Fsideshow/lists"}