playdemo

Record Playwright demo specs as gifs and embed them in PR bodies.

Why a gif? It's the only format GitHub renders inline in a PR body — screenshots miss the flow, video tags get stripped, and CI-artifact links require a click-through.

Ships as a skill that works across coding agents (Claude Code, Cursor, OpenCode, Codex, GitHub Copilot, and 50+ others) — installable in one command via the open Agent Skills standard.

Requirements

• Node 22+
• ffmpeg on PATH (brew install ffmpeg on macOS)
• A project with @playwright/test installed

Install

As a skill (recommended)

# Per-project (writes to .claude/skills/, .agents/skills/, etc. — committed alongside your code)
npx skills add henriquerferrer/playdemo

# Personal / global (writes to ~/.claude/skills/, ~/.cursor/skills/, etc.)
npx skills add henriquerferrer/playdemo --global

# Target a specific agent (auto-detected by default)
npx skills add henriquerferrer/playdemo -a claude-code

npx skills (vercel-labs/skills) clones this repo and copies skills/recording-pr-demos/ — including the bundled scripts/playdemo.mjs — to the appropriate per-agent path. No npm install needed; the skill is self-contained.

After install, your agent can record demos as part of its PR-creation workflow. See the bundled SKILL.md for the orchestration.

Also available as a CLI

For CI runners, npm scripts, or any non-agent workflow, the same recording pipeline ships as a CLI on npm.

Per-project (recommended for projects with demo specs) — pin alongside @playwright/test:

npm i -D playdemo @playwright/test

Then invoke via npx playdemo …, an npm script ("demo": "playdemo record …"), or pnpm playdemo ….

Globally — for ad-hoc use across many projects:

# npm
npm i -g playdemo

# mise
mise use -g npm:playdemo

# Homebrew (planned — not published yet)
brew install playdemo

Per-project with mise — pin in mise.toml:

[tools]
node = "22"
"npm:playdemo" = "0.2.0"

Then mise install. @playwright/test is a peer dep — install it via npm in your package.json even when using mise for the CLI.

From source (development / collaborators only):

git clone [email protected]:henriquerferrer/playdemo.git
cd playdemo && npm install && npm run build && npm link

After install, playdemo is on your PATH (for global / source installs) or available via npx/npm scripts (for per-project installs).

Usage

playdemo record demos/<feature>.spec.ts > .demos/<feature>.snippet.md
git add .demos/<feature>.gif

The CLI prints a markdown snippet to stdout that can be pasted into a PR body:

### Demo: <feature>
![<feature> demo](.demos/<feature>.gif)

Flags

| flag | default | description | | -------------------- | ------------ | ------------------------------------------ | | --test <name> | first test | Run only the named test in the spec | | --out <path> | .demos/... | Override gif output path | | --width <px> | 720 | Gif width | | --fps <n> | 24 | Frames per second | | --max-seconds <n> | 30 | Hard cap on duration |

A playdemo.config.json at the repo root sets project-wide defaults:

{
  "fps": 24,
  "width": 720,
  "maxSeconds": 30,
  "outputDir": ".demos"
}

CLI flags override config-file values; config values override built-in defaults.

Design

See docs/specs/2026-05-01-playdemo-design.md.

License

MIT — see LICENSE.