demo-this-pr

demo-this-pr records the current local change before you open a pull request. Run one command from a working tree, get an isolated Chromium demo, a local MP4 with cursor/highlight overlays, captured test output, and a review report that explains what changed.

It is not an AI detector. It is a PR-quality tool for avoiding vague descriptions, missing demos, and unverifiable testing claims.

One Command

Run this from the repository that has local or unpushed changes:

demo-this-pr

Or point it at a repository from anywhere:

demo-this-pr --cwd /path/to/repository
# or
demo-this-pr /path/to/repository

The command will:

• detect branch changes, including uncommitted files;
• start the repository dev server when a dev script exists;
• otherwise use a reachable local app on a common localhost port;
• open isolated Playwright Chromium, never the user's normal Chrome profile;
• record a slow local MP4 with captions, cursor movement, and highlighted elements;
• run inferred safe test commands from package.json;
• open a local report so the user can press play immediately;
• write artifacts into a unique directory under .demo-this-pr/runs/.

Each execution gets its own run directory, for example:

.demo-this-pr/runs/20260515-164322-381-my-feature/

The run label comes from the current branch, then package.json name, then the folder name. Non-meaningful Git labels such as HEAD or unknown are not used in generated directory names. Artifacts from previous runs are not overwritten unless you explicitly pass --output.

Installation

During local development of this tool:

npm install
npm run build
npm link

After publishing to npm, the intended installation paths are:

npm install -g demo-this-pr

or per repository:

npm install --save-dev demo-this-pr
npx demo-this-pr

For CI or agent runners, prefer a pinned package version and a deterministic artifact directory:

npx [email protected] ci

The command exits non-zero when Git context or a reachable local app is missing. CI systems can archive .demo-this-pr/ci/ as a build artifact after the command finishes.

Publishing From A Private Repository

The source repository can remain private. The lowest-friction public distribution path is a public npm package named demo-this-pr that ships only the compiled CLI, assets, README, package metadata, and license.

Recommended package surface:

• npm package: demo-this-pr.
• CLI binary: demo-this-pr.
• Optional short alias: demo-pr.
• Public files: dist/, assets/, README.md, package.json, and LICENSE.
• Private files: source history, local .demo-this-pr/ runs, generated videos, and internal planning notes.

When the repository is private, avoid public npm metadata that points to private GitHub issues or a private README URL. Add repository, bugs, and homepage later if there is a public docs site, public landing page, or public mirror.

Pre-publish checks:

npm run publish:check
npm run publish:npm

npm run publish:check builds the TypeScript output, runs tests, and verifies the package contents with npm pack --dry-run. npm run publish:npm publishes from a generated staging directory so npm can use a registry-friendly README without changing the GitHub README.

Requirements

Runtime requirements:

• Node.js >=20.
• Git CLI available in PATH.
• A Git working tree; uncommitted files are supported.
• Run the command from inside the repository that contains the changes, or pass --cwd <repo> / [repo]. The automatic flow exits if Git context is unavailable instead of generating a generic report.
• A local web application reachable by HTTP.
• Playwright Chromium installed for the machine running the tool.

Target project requirements:

• Best case: a package.json with a dev script that prints a localhost URL.
• Supported package managers for auto-start: npm, pnpm, Yarn, and Bun.
• Supported app URLs for fallback detection include common localhost ports: 3000, 3001, 5173, 4173, 4321, 8080, and 8000.
• Optional test scripts: test:ci, test, typecheck, and lint.

If Chromium is missing, install it once:

npx playwright install chromium

Technical Stack

demo-this-pr is a Node.js CLI implemented in TypeScript.

Core stack:

• TypeScript with ESM output.
• Node.js child_process for dev-server and test-command orchestration.
• Git CLI for branch, base, commit, and working-tree metadata.
• Commander for CLI parsing.
• Playwright for isolated Chromium automation, local video capture, screenshots, and report playback.
• ffmpeg-static for WebM-to-MP4 conversion.
• picocolors for terminal output.
• Vitest for unit tests.

Runtime architecture:

• src/auto.ts detects repository context, starts or discovers the local app, infers tests, and builds the default demo plan.
• src/playwright.ts records the Chromium demo, renders overlays, captures screenshots, and converts video to MP4.
• src/prKit.ts writes the review kit.
• src/report.ts renders Markdown and HTML reports.
• src/viewer.ts opens the generated HTML report in isolated Chromium and exits when the viewer closes.

No LLM or external API is required.

Output

A normal run writes:

.demo-this-pr/runs/<run-id>/
  PR_REVIEW.md
  PR_REVIEW.html
  MCP_PLAYWRIGHT.md
  mcp-playwright-demo.js
  demo-plan.json
  pr-demo.spec.ts
  playwright.config.ts
  assets/
    demo-this-pr.mp4
    demo-this-pr.webm
    screenshots/
    mcp-screenshots/
    test-results/

The generated video is local review evidence. .demo-this-pr/ is ignored by git and the MP4 is not uploaded automatically.

Common Commands

Generate and open the report:

demo-this-pr

Generate without opening the report viewer:

demo-this-pr --no-open

Run without a visible browser window:

demo-this-pr --headless

Write to an explicit directory:

demo-this-pr --output .demo-this-pr/manual-checkout-demo

Generate in CI without a visible browser or report viewer:

demo-this-pr ci

Delete all generated run artifacts for the current repository:

demo-this-pr runs --delete

Jenkins example:

stage('PR demo') {
  steps {
    sh 'npm ci'
    sh 'npx [email protected] ci'
  }
  post {
    always {
      archiveArtifacts artifacts: '.demo-this-pr/ci/**', allowEmptyArchive: true
    }
  }
}

demo-this-pr ci starts the repository dev script when one exists. If the application needs a non-standard start command, start it in the pipeline and run the explicit demo command with --url.

Use an explicit flow:

demo-this-pr demo \
  --url http://localhost:3000 \
  --feature "Project creation flow" \
  --why "Users can create projects without leaving the dashboard" \
  --change "Project creation now happens inline" \
  --tech "Next.js server actions and React form state" \
  --step "goto:/dashboard" \
  --step "click:text=New project" \
  --step "fill:input[name=name]:Demo Project" \
  --step "click:text=Create" \
  --step "expect:Demo Project" \
  --test "npm test"

Demo Step DSL

goto:/path
click:text=Button label
fill:input[name=email]:[email protected]
press:input[name=q]:Enter
expect:Expected text on screen
screenshot:after-action
wait:500

For richer demos, generate a JSON plan:

demo-this-pr init-demo --output demo-this-pr.demo.json

Then run:

demo-this-pr demo --demo-plan demo-this-pr.demo.json

Playwright MCP

Every run also writes an MCP-first browser verification guide:

MCP_PLAYWRIGHT.md
mcp-playwright-demo.js

Agents with Playwright MCP can load mcp-playwright-demo.js through mcp__playwright__.browser_run_code_unsafe, run the same browser flow, capture screenshots, and close the MCP tab afterwards.

Development

npm install
npm run build
npm test
npm run check

The repository includes a root AGENTS.md with the local browser-testing policy and implementation standards for future agents.