ShowRunner

Workflow capture and grounding system

ShowRunner captures how work gets done — not just what it looks like — so workflows can be documented, shared, and eventually replayed.

Unlike screen recorders (Loom, OBS) or marketing tools (Arcade), ShowRunner produces structured, executable artifacts: temporal event logs, semantic annotations, and reproducible step sequences.

Built for developers and teams who need to document operational workflows, onboard teammates, or create reproducible process guides.

Features

Capture

• Multi-display screen recording (display, window, or region)
• Click and keyboard/app-focus event capture with timestamps
• Optional browser DOM-semantics capture (Chrome extension -> dom_* events)
• Terminal session recording (optional terminal.cast capture)
• Step markers during recording

Structure

• Timeline editor with hotspot annotations
• AI-assisted step detection and action typing
• Structured event log (events.ndjson) for replay
• Click ripple visualization

Export

• Markdown documentation generation
• MP4 export (optional chapter cards)
• Embeddable widget player
• Share links for team distribution

Tech Stack

• Desktop: Tauri (Rust backend + React frontend)
• UI: React 18 + TypeScript + React Router
• Backend: Rust Tauri host + Python FastAPI sidecar for accessibility/event capture + AI analysis
• Storage: Local filesystem (sessions stored in ~/Library/Application Support/ShowRunner/)

Development Setup

Prerequisites

• Node.js >= 18
• Rust >= 1.93 (install via rustup)
• Python >= 3.11
• FFmpeg (for export functionality)

Quick Start

# Install dependencies
npm install
cd python_sidecar && python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]' && cd ..

# Run development environment (Python sidecar + Tauri)
./scripts/dev.sh

The app will open automatically, and the Python sidecar will run on http://127.0.0.1:8765.

Manual Development

# Terminal 1: Python sidecar
cd python_sidecar
source .venv/bin/activate
python3 -m uvicorn python_sidecar.main:app --reload

# Terminal 2: Tauri app
npm run tauri:dev

Packaging & Distribution (macOS)

Fastest tester distribution (unsigned beta zip)

./scripts/package-beta-macos.sh

This creates:

• artifacts/beta/ShowRunner-macos-beta.zip

You can share that zip directly with testers for rapid feedback.

GitHub option:

• Run the Desktop Beta Artifact workflow (manual dispatch) and download the zip from workflow artifacts.

Local beta build

# Build bundled Python sidecar executable into src-tauri/binaries/
./scripts/build-sidecar.sh

# Build desktop app bundle
npm run tauri:build -- --bundles app

Build output:

• src-tauri/target/release/bundle/macos/ShowRunner.app

CI release pipeline

Tagging v* runs .github/workflows/release.yml, which:

1. Builds a packaged sidecar binary.
2. Builds a signed Tauri macOS app bundle.
3. Publishes a draft GitHub Release artifact.

Required GitHub secrets for signing/notarization:

• APPLE_CERTIFICATE
• APPLE_CERTIFICATE_PASSWORD
• APPLE_SIGNING_IDENTITY
• APPLE_ID
• APPLE_PASSWORD
• APPLE_TEAM_ID

Project Structure

showrunner/
├── src/                     # React frontend
│   ├── views/               # Recording, Editor, Upload views
│   ├── components/          # UI components
│   └── lib/                 # API wrappers
├── src-tauri/               # Rust backend
│   └── src/
│       ├── recording.rs     # Screen capture
│       ├── devices.rs       # Device enumeration
│       ├── session.rs       # Session storage
│       ├── python_bridge.rs # HTTP client for sidecar
│       └── errors.rs        # Error taxonomy
├── python_sidecar/          # FastAPI sidecar
│   ├── api/                 # Event, export, upload endpoints
│   └── services/            # Overlay mapping, FFmpeg rendering
└── scripts/                 # Development utilities

Code Quality

Rust

cargo build --manifest-path src-tauri/Cargo.toml
cargo test --manifest-path src-tauri/Cargo.toml

Python (Strict Type Checking)

cd python_sidecar
source .venv/bin/activate
mypy .                  # Must pass strict mode
ruff check .            # Must pass with no errors
pytest                  # Run tests

TypeScript

npm run build           # Type-checks + builds
npm run lint            # ESLint checks for TS/TSX
npm run format:check    # Prettier formatting check

Pre-commit Hooks

python3 -m pip install pre-commit
pre-commit install
pre-commit run --all-files

Session Data Model

Sessions are stored in ~/Library/Application Support/ShowRunner/sessions/{session_id}/:

| File | Purpose | | --------------- | --------------------------------------------------------------------------- | | recording.mp4 | Visual recording (never modified) | | events.ndjson | Append-only event log — app focus, key metadata, shortcuts, clicks, markers | | steps.json | Structured workflow steps with action typing | | edits.json | Non-destructive edit patches | | metadata.json | Session info (timestamp, display, duration) |

The events.ndjson format is designed for replay — each line is a timestamped event that can be used for documentation, assisted replay, or eventual automated execution.

Notes:

• Alphanumeric key values are redacted by default ("<redacted>").
• For richer web workflows (search, form submit, “open first email”), you can load the optional Chrome extension from docs/ (see docs/SHOWRUNNER_DOM_CAPTURE_EXTENSION.md).
• Region capture on macOS requires careful coordinate handling (Retina / mixed-DPI). See SYSTEM_DESIGN.md section "Region Capture (macOS): Coordinate Spaces + Persistent Frame".
• Auto Steps / Generate Steps from Activity runs in the editor client using captured timeline events and clicks.
• Export now shows persistent in-app status with output path (copy/reveal actions).

Roadmap

✅ Phase 1: Capture (Complete)

• Tauri + React infrastructure with multi-window architecture
• Display, window, and region capture modes
• Click/keyboard event capture during recording
• Step markers and countdown timer
• Terminal session recording

✅ Phase 2: Structure (Complete)

• Timeline editor with hotspot annotations
• Click ripple visualization
• AI-assisted step detection
• Markdown documentation export
• Embeddable widget player

🚧 Phase 3: Enhanced Capture (In Progress)

• Audio capture (mic + system audio)
• Keyboard shortcut visualization
• Accessibility-based action typing (app-dependent)
• Improved step boundary detection

📋 Phase 4: Assisted Replay (Planned)

• Ghost overlay highlights next target during playback
• Step-by-step guided execution
• Workflow validation (did user complete step correctly?)

📋 Phase 5: Optional Execution (Future)

• Agent-driven replay with human approval
• Per-step execution controls
• Dry-run mode

Contributing

See implementation_plan.md for detailed architecture and commit strategy.

License

MIT