Metadata-Version: 2.4
Name: showtime-review
Version: 0.2.0
Summary: Browser review loop for agent-authored plans
Author: Darrick Oliver
License-Expression: MIT
Project-URL: Homepage, https://github.com/Darrick-Oliver/showtime-skill
Project-URL: Repository, https://github.com/Darrick-Oliver/showtime-skill
Project-URL: Issues, https://github.com/Darrick-Oliver/showtime-skill/issues
Keywords: agent-skills,planning,review,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Showtime

An [Agent Skills](https://agentskills.io) 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.

![The Showtime shell reviewing an artifact](docs/screenshot.png)

- Agent-facing contract: [src/showtime/skill/SKILL.md](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:

```bash
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:

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

## Update

Upgrade the shared runtime, then refresh each installed adapter:

```bash
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`:

```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

```text
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:

```bash
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.
