pr-visual

pr-visual

A Claude Code plugin that captures visual PR documentation: AI-generated Playwright scenarios from the PR description or git diff, annotated screenshots (desktop 2x + mobile 3x, light + dark), and walkthrough videos with burned-in captions.

Each run is isolated in a git worktree with its own port and namespaced resources (Docker containers, networks, volumes), so multiple runs can execute in parallel without collisions.

Prerequisites

• Node.js 20+
• ffmpeg — brew install ffmpeg (optional — needed for video captions and voice-over transcoding)
• GitHub CLI — brew install gh
• Chromium (installed automatically via Playwright on postinstall)

Installation

From Claude Code marketplace (recommended)

/plugin marketplace add gerokeller/pr-visual

Then install the plugin:

/plugin install pr-visual

To share with your team, add this to your project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "pr-visual": {
      "source": {
        "source": "github",
        "repo": "gerokeller/pr-visual"
      }
    }
  },
  "enabledPlugins": {
    "pr-visual@pr-visual": true
  }
}

Via npm

npm install -D pr-visual

Claude Code automatically discovers the plugin via .claude-plugin/plugin.json inside node_modules/pr-visual/. This gives you:

• /pr-visual slash command
• PostToolUse hook that reminds you to run it after gh pr create

Quick start

1. Scaffold the config

/pr-visual init

Or via CLI:

npx pr-visual init

This detects your project setup and generates a tailored .pr-visual.config.ts:

pr-visual init: Detecting project setup...
  Framework:       Next.js
  Package manager: pnpm
  Docker:          yes (postgres, redis)
  ORM:             prisma
  Health endpoint: /api/health
  Default port:    3000

  Created: .pr-visual.config.ts

2. Review and commit the config

The generated config is ready to use but worth reviewing. Commit it so every team member gets the same behavior.

3. Run it

/pr-visual

Or manually:

npx pr-visual

Configuration

Plugin settings

The plugin accepts the following user configuration (set during plugin install or in settings):

Setting	Description
anthropic_api_key	API key for AI-generated scenarios (stored in system keychain). Falls back to ANTHROPIC_API_KEY env var, then to static route capture.

Project config

.pr-visual.config.ts is the contract between your project and the recorder. It declares everything needed to bring up the application from a cold worktree:

import type { ProjectConfig } from "pr-visual/scripts/pr-visual/types.js";

export default {
  port: 3000,

  devServer: {
    command: "npm run dev",
    env: { PORT: "{{port}}" },
  },

  // Setup steps — Docker resources are auto-scoped via COMPOSE_PROJECT_NAME
  setup: [
    { name: "Start database", command: "docker compose up -d postgres redis" },
    { name: "Run migrations", command: "npx prisma migrate deploy" },
    { name: "Seed data", command: "npx prisma db seed" },
  ],

  readiness: {
    path: "/api/health",
    status: 200,
    timeout: 60_000,
  },

  // Teardown — only this run's containers are removed
  teardown: [
    { name: "Stop database", command: "docker compose down -v" },
  ],

  isolate: true,
  installCommand: "npm ci",
} satisfies ProjectConfig;

Template variables

All command strings and env values support these placeholders:

Variable	Description
{{port}}	Auto-allocated TCP port for this run
{{runId}}	Unique run identifier — safe as Docker project name, DB suffix, directory name
{{rootDir}}	Absolute path to the working directory (worktree or project root)

Automatic resource isolation

Every lifecycle step and the dev server receive these environment variables automatically — no manual setup needed:

Variable	Value	Purpose
COMPOSE_PROJECT_NAME	{{runId}}	Scopes all Docker Compose containers, networks, and volumes to this run
PORT	Allocated port	Standard port variable
PR_VISUAL_RUN_ID	{{runId}}	Available for custom scripts
PR_VISUAL_PORT	Allocated port	Available for custom scripts
PR_VISUAL_ROOT_DIR	{{rootDir}}	Available for custom scripts

This means docker compose up -d postgres in two parallel runs creates two independent Postgres containers, and each run's docker compose down -v only removes its own.

Config reference