Showtime

An Agent Skills review loop. An agent presents work - a plan, a diagram, anything that deserves eyes - as a single-page HTML artifact, hosts it in a dark browser shell, and blocks until the user marks the review done or returns a comment batch.

• Agent-facing contract: src/showtime/skill/SKILL.md
• Runtime: Python 3.8+, standard library only
• Contributor UI: React, TypeScript, Vite, and Tailwind

Install

Install the runtime once, then copy thin skill adapters into every harness that should discover Showtime:

uv tool install showtime-review
showtime skill install agents

pipx install showtime-review is equivalent.

Known destinations are agents, claude, codex, and pi; several may be installed together. Use --destination for another harness. skill install never overwrites a non-empty directory. To replace an old full clone with a thin adapter and timestamped backup, preview the operation first:

showtime skill migrate agents --dry-run
showtime skill migrate agents
showtime doctor

Update

Upgrade the shared runtime, then refresh each installed adapter:

uv tool upgrade showtime-review
showtime skill install agents
showtime doctor

For pipx installations, use pipx upgrade showtime-review followed by the same adapter command. Managed adapter updates are idempotent. Runtime upgrades never touch project artifacts or sidecars.

Codex sandbox setup

Showtime hosts the shell on 127.0.0.1. In Codex, prefer a scoped sandbox approval when showtime serve asks to bind its loopback server. If Showtime is used across many projects, enable networking for the global workspace-write sandbox in ~/.codex/config.toml:

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

Start a new Codex session after changing the config. For one session only, launch Codex with --config sandbox_workspace_write.network_access=true. This setting permits general network access inside the workspace sandbox, not only loopback; managed workspace policy may prohibit it. showtime doctor checks whether a loopback bind is available. The runtime itself always binds 127.0.0.1 only.

Architecture

src/showtime/cli.py       CLI, stdlib server, review protocol, adapter installer
  serve ARTIFACT         start/reuse the long-lived review server; block on
                         an attach for one round's outcome
  reply ARTIFACT FILE    validated agent reply channel (submits to the server)
  reattach ARTIFACT ID   repair or accept an orphaned thread anchor
  templates              list the template library
  template NAME          print one resolved template's instructions
  doctor                 verify runtime assets and installed adapters
  skill install|migrate  manage thin harness adapters

src/showtime/templates/  bundled templates (plan-brief)
src/showtime/ui/         compiled shell and iframe agent, bundled in the wheel
src/showtime/skill/      thin Agent Skill adapter and its authoring docs
scripts/showtime.py      source-checkout compatibility launcher

ui/src/shell/            React shell: chips, popover, drawer, composers
ui/src/agent/            iframe agent: quote anchoring and layout bridge
ui/src/protocol.ts       shared protocol and sidecar types

The shell frames the artifact in an iframe and communicates with the injected iframe agent over postMessage. Sibling asset files next to the artifact are served alongside it; the entry document stays the unit of review. Threads persist in a server-owned sidecar next to the artifact. The runtime binds 127.0.0.1 only. The review's conclusion is stamped into the artifact itself.

The server outlives the round: a user batch ends the agent's blocking attach, not the process, so the page stays live while the agent works and comments sent meanwhile queue for the next batch. Vacancy shutdown (no attach held for the grace period) or done-delivery ends the server. Each round that changes the artifact's files publishes a version snapshot under <artifact-stem>.versions/; the shell lets the user flip back to old versions read-only, with their frozen transcripts.

Templates are markdown instruction documents discovered from <cwd>/.showtime/templates/, ~/.showtime/templates/, and the bundled set, merged with nearest-wins shadowing. See the adapter's docs/templates.md for the authoring format.

Developing

The Python runtime has no dependencies. Node 20+ is required only to change the shell:

cd ui
npm install
npm run build      # typecheck + builds -> src/showtime/ui/
npm test           # Vitest unit tests
npm run e2e        # Playwright against scripts/showtime.py
npm run dev        # shell only; artifact routes require `showtime serve`

src/showtime/ui/ is committed and included as wheel package data. Rebuild and commit it with every UI change; there is no CI check for stale assets.

Release

The package version has one source: src/showtime/__init__.py. To release:

1. Update __version__ and commit it.
2. Create a GitHub release tagged with the same version prefixed by v, such as v0.2.0.
3. The publish.yml workflow verifies the tag, builds the wheel and source distribution, and publishes them to PyPI through OIDC trusted publishing.

One-time PyPI setup is required: register a pending trusted publisher for project showtime-review, owner Darrick-Oliver, repository showtime-skill, workflow publish.yml, and GitHub environment pypi. Add required reviewers to that environment before the first release. No PyPI token or GitHub secret is needed.