<p align="center">
<img src="assets/brand/showoff-logo.jpg" alt="The Showrunner, an original mechanical aperture mascot presenting a polished cinematic frame" width="180">
</p>
<h1 align="center">ShowOff</h1>
<p align="center">
<strong>Evidence in. Cinema out. And now: give Claude eyes.</strong><br>
Two Claude Code skills in one plugin. Turn any project, pull request, live app, or
evidence folder into a cinematic, source-grounded showcase -- and let Claude actually
watch, transcribe, and understand any video or screen recording.
</p>
<p align="center">
<img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-2.1.198%2B-D97706?style=flat-square">
<img alt="HyperFrames" src="https://img.shields.io/badge/HyperFrames-0.6%2B-C65A24?style=flat-square">
<img alt="FFmpeg" src="https://img.shields.io/badge/FFmpeg-6%2B-5A8F29?style=flat-square">
<img alt="yt-dlp" src="https://img.shields.io/badge/yt--dlp-supported-C65A24?style=flat-square">
<img alt="MIT License" src="https://img.shields.io/badge/license-MIT-2B2B2B?style=flat-square">
</p>
<p align="center">
<code>/showoff</code> makes the video. <code>/figureout</code> watches one.
</p>
## The two skills
| Skill | What it does |
|-------|--------------|
| **`/showoff`** | Turns a project, PR, app, or evidence folder into a polished showcase video, poster, plan, and share copy. Parallel research lanes, every claim verified before render. |
| **`/figureout`** | Gives Claude the ability to **watch any video**. Point it at a YouTube link or a local file and Claude sees the frames and reads the transcript, then answers your questions with timestamps. |
## Give Claude eyes: `/figureout`
Claude cannot watch a video. `/figureout` fixes that.
Hand it a public video URL or a local file, and it pulls a **timestamped transcript**
(native captions first, with a Whisper fallback) and extracts **auto-scaled frames** with
FFmpeg. Claude then reads those frames as images and combines them with the transcript --
so by the time it answers, it has genuinely seen and heard the video.
```
/figureout https://www.youtube.com/watch?v=... what happens in this video?
/figureout ./screen-recording.mp4 summarize the bug being demonstrated
/figureout https://youtu.be/... --start 00:30 --end 00:45 zoom in on one moment
```
- **Captions-first, Whisper-fallback.** Free and instant when captions exist; falls back to
Groq or OpenAI Whisper (extracted audio only) when they do not.
- **Smart frame budgets.** Scene-aware sampling, perceptual de-duplication, and auto-scaled
resolution keep the frame set small but representative.
- **Focus mode and cue frames.** Narrow to a time window, or pin exact timestamps to
inspect specific moments frame by frame.
- **Feeds `/showoff`.** Pass `--feed-showoff` to emit a structured analysis a `/showoff` run
can ingest as grounded evidence -- watch a demo recording, then showcase it.
Full details: [skills/figureout/SKILL.md](skills/figureout/SKILL.md).
<p align="center">
One command. Five independent research lanes. Every claim verified before render.
</p>
## Why ShowOff
- **Two skills, one install.** `/showoff` produces cinema; `/figureout` gives Claude the
eyes to watch any video. They compose: analyze a recording, then showcase it.
- **Parallel by design.** Evidence, narrative, visuals, proof, and taste are researched
independently, then reconciled by one orchestrator.
- **Grounded in the real project.** Unsourced metrics, invented features, and fake UI are
excluded before they reach the screen.
- **Taste is a gate, not a prompt adjective.** Explicit design dials govern typography,
density, motion, accessibility, and anti-template checks.
- **Delivery is verified.** HyperFrames must pass its checks, preview approval is required,
and the poster is pixel-matched against the MP4's actual frame zero.
> [!NOTE]
> **Build provenance:** ShowOff was built by **Goose** using
> **[Phoenix](https://github.com/All-The-Vibes/ATV-Phoenix)**, a harness for building and
> operating outer-loop systems.
## Install
### As standalone skills (recommended)
```
npx skills add https://github.com/All-The-Vibes/ShowOff --skill showoff
npx skills add https://github.com/All-The-Vibes/ShowOff --skill figureout
```
This installs the standalone skills, invoked as `/showoff` and `/figureout`.
### As a Claude Code plugin
```
/plugin marketplace add All-The-Vibes/ShowOff
/plugin install showoff@showoff
```
Installing the plugin brings both skills. Claude Code namespaces plugin skills, so with this
install method invoke `/showoff:showoff` and `/showoff:figureout` instead of the bare names.
## Usage
The examples below use the recommended standalone skill install.
### `/showoff` -- make the showcase
```
/showoff auto-detect the current project (cwd)
/showoff https://demo.myapp.io a running app or website
/showoff https://github.com/acme/app/pull/42 a GitHub PR
/showoff ./evidence a supplied evidence path (no git needed)
/showoff --format vertical portrait 9:16 output
/showoff --narration add a narration track, captions, transcript
/showoff --duration 40 --goal pitch 40-second pitch
/showoff --media approved auto-approve grounded media opportunities
/showoff --title "My Project" --tone bold set the title and tone
/showoff showoff-output/20260721-101500 resume and re-render the poster
```
#### `/showoff` flags
| Flag | Values | Default |
|------|--------|---------|
| `--tone` | any preset or freeform phrase | `professional` |
| `--format` | `landscape`, `vertical`, `square` | `landscape` |
| `--duration` | integer 10-90 (seconds) | `25` |
| `--audience` | any phrase | `general` |
| `--goal` | `demo`, `pitch`, `update`, `tutorial` | `demo` |
| `--narration` | flag (no value) | off |
| `--media` | `auto`, `approved`, `none` | `auto` |
| `--title` | quoted string | inferred |
| positional | project path, GitHub PR URL, or app URL | cwd |
To resume a prior run, pass its timestamped output directory as the positional argument
plus a plain-language instruction. There is no resume flag.
**Run vs. resume:** if the run directory is **incomplete** (not `done`), ShowOff continues
in the same directory, repairing or adding only missing artifacts. If the run directory is
**done**, ShowOff treats it as source material and creates a new timestamped sibling --
it never writes into a completed run.
### `/figureout` -- watch a video
```
/figureout https://www.youtube.com/watch?v=... watch and summarize a video
/figureout ./demo.mp4 what feature is shown? ask a question about a local file
/figureout <url> --detail transcript transcript-only, no video download
/figureout <url> --start 00:30 --end 00:45 focus on a time window
/figureout <url> --timestamps "00:10,01:22" pin exact moments as cue frames
/figureout <url> --feed-showoff emit analysis for a /showoff run to ingest
```
#### `/figureout` flags
| Flag | Values | Default |
|------|--------|---------|
| positional | public video URL or local video path | required |
| `--question` | quoted string (or trailing free text) | none |
| `--detail` | `transcript`, `efficient`, `balanced`, `token-burner` | `balanced` |
| `--start` / `--end` | seconds or `MM:SS` (focus window) | full video |
| `--timestamps` | comma list of `MM:SS` cue frames | none |
| `--resolution` | frame width in px | `512` |
| `--no-dedup` | flag (no value); keep near-duplicate frames | dedup on |
| `--no-whisper` | flag (no value); never fall back to Whisper | fallback on |
| `--out-dir` | path for the working directory | system temp |
| `--feed-showoff` | flag (no value); write `figureout-analysis.json` | off |
## How it works
```
/showoff invoked
|
v
+---------------------------+
| State sensor | project-context.mjs + validate-output.mjs
+---------------------------+
|
v
+---------------------------------------------------------------+
| Five read-only worker lanes (parallel, return findings) |
| evidence-investigator product-narrator visual-curator |
| proof-auditor taste-director |
+---------------------------------------------------------------+
|
v
+---------------------------+
| Orchestrator reconciles | verifies claims, drops UNVERIFIED,
| and writes the artifacts | writes dossier + plan (only writer)
+---------------------------+
|
v
+---------------------------+
| Media opportunity pass | one checkpoint; --media auto/approved/none
+---------------------------+
|
v
+---------------------------+
| HyperFrames composition | check, preview approval, render
+---------------------------+
|
v
showoff-output\<YYYYMMDD-HHMMSS>\
evidence-dossier.md
showoff-plan.md
composition-brief.md
composition\ (HyperFrames project)
showoff.mp4
showoff.jpg
share-copy.md
showoff-manifest.json
captions.vtt (narration only)
transcript.md (narration only)
```
HyperFrames owns the composition mechanics, check, preview, and render. Media OS owns asset
resolution and generation, and only after explicit approval. ShowOff never publishes.
## Requirements
| Component | Minimum version | Used by |
|-----------------|----------------------------|---------|
| Claude Code | 2.1.198 | both |
| Node.js | 22.0.0 | both |
| FFmpeg | 6.0 | both |
| HyperFrames | installed and on PATH | `/showoff` |
| yt-dlp | installed and on PATH | `/figureout` (URL sources) |
| Groq or OpenAI API key | optional | `/figureout` (Whisper fallback when captions are absent) |
`/figureout` ships a setup preflight (`scripts/setup.mjs`) that checks for FFmpeg, ffprobe,
and yt-dlp and scaffolds a config file for an optional Whisper key.
## Outputs
Every normal invocation writes a new timestamped directory under `showoff-output\` in the
project root. A prior run is never overwritten. Resuming an incomplete run continues in the
same directory; invoking with a completed run as the positional creates a new sibling.
- `evidence-dossier.md` -- reconciled, sourced facts
- `showoff-plan.md` -- narrative, visual assets, proof audit, taste, scene breakdown
- `composition-brief.md` -- the brief handed to HyperFrames
- `composition\` -- the HyperFrames project
- `showoff.mp4` -- the composed video (25 s default, 10-90 s accepted)
- `showoff.jpg` -- the strongest settled frame, baked as frame 0
- `share-copy.md` -- platform-ready share copy
- `showoff-manifest.json` -- provenance, config, reproducibility, and claims
- `captions.vtt` and `transcript.md` -- only when `--narration` is set
## Privacy and boundary
ShowOff never automatically publishes or uploads the finished video, poster, or any
artifact. It writes only to the local timestamped run directory and records `published:
false` in the manifest.
External network access is limited and explicit. ShowOff may contact the network only to:
inspect a supplied PR URL or app URL, run Claude Code model work, update the HyperFrames
sub-skill, and send explicitly approved requests to Media OS providers. Media providers
receive only the approved request payload; project evidence is not uploaded without an
approved Media OS request, and credential files are never read. Every external endpoint
actually contacted is recorded in the manifest's `external_services_used`. ShowOff does not
overstate privacy or imply the machine never reaches the network.
## Validate and test
```
npm test
```
`npm test` runs the repository validator (`scripts/validate-skill.mjs`) and the runtime
tests (`scripts/test-runtime.mjs`). The validator checks required files, SKILL.md
frontmatter and resolvable references, JSON integrity, version agreement across manifests,
script syntax, em dash hygiene, placeholder content, and the absence of obsolete flags or
output names. The runtime tests exercise `project-context.mjs` and `validate-output.mjs`
against temporary fixtures, including a poster frame-zero pixel-match test that decodes
both `showoff.mp4` and `showoff.jpg` to raw rgb24 via FFmpeg and verifies the mean
absolute error is at or below 3.0. FFmpeg is required for `npm test`; it is already listed
under Requirements.
You can also validate the plugin manifest:
```
claude plugin validate .
```
## Repository layout
```
ShowOff/
.claude-plugin/ plugin.json and marketplace.json
docs/ architecture.md
evals/ evals.json
scripts/ validate-skill.mjs, test-runtime.mjs
skills/
showoff/
SKILL.md
references/ orchestration, project-inspection, narrative, taste,
media, composition, delivery
templates/ showoff-plan.md, composition-brief.md
scripts/ project-context.mjs, validate-output.mjs
figureout/
SKILL.md
references/ pipeline, transcription, setup, showoff-bridge
templates/ analysis-report.md
scripts/ figureout.mjs, frames.mjs, transcribe.mjs, whisper.mjs,
config.mjs, setup.mjs, project-context.mjs, showoff-bridge.mjs
CONTRIBUTING.md
LICENSE
README.md
SECURITY.md
package.json
```
## Inspiration
ShowOff is an original implementation. The general concept of automating project showcase
creation was inspired by work in the open-source community, including the idea explored at
https://github.com/latent-spaces/brag. ShowOff shares no code, assets, or phrasing with
that project and is not affiliated with it.
## License
MIT. See [LICENSE](LICENSE).