showtime-review 0.1.1

Browser review loop for agent-authored plans

Showtime

An Agent Skills review loop for plans. An agent turns a finished plan into a single-page HTML artifact, hosts it in a dark browser shell, and blocks until the user approves 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         host the review and block for its outcome
  reply ARTIFACT FILE    validated agent reply channel into the sidecar
  reattach ARTIFACT ID   repair or accept an orphaned thread anchor
  config                 resolve and print the section contract
  doctor                 verify runtime assets and installed adapters
  skill install|migrate  manage thin harness adapters

src/showtime/config.json runtime-default section contract
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. Threads persist in a server-owned sidecar next to the artifact. The runtime binds 127.0.0.1 only. Approval is stamped into the artifact itself.

Config resolves whole-file layers in this order: <cwd>/.showtime/config.json, ~/.showtime/config.json, then the runtime default. See the adapter's docs/config.md for its schema and section obligations.

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.