Metadata-Version: 2.4
Name: showtime-review
Version: 0.1.1
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 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.

![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         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:

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