agentreel 0.3.5 → 0.4.1

package/README.md

@@ -1,10 +1,10 @@
 # agentreel
 
-Turn your web apps and CLIs into viral clips.
+Turn your web apps and CLIs into viral clips — or demo what a PR does.
 
 https://github.com/user-attachments/assets/474fd85d-3b35-48f4-82b8-1b337840fb51
 
-> 🔊 Turn on sound
+> Turn on sound
 
 ## Install
 
@@ -15,46 +15,72 @@ npx agentreel
 ## Usage
 
 ```bash
+# Demo a PR (reads context from GitHub):
+agentreel --pr 123
+agentreel --pr owner/repo#123
+agentreel --pr https://github.com/owner/repo/pull/123
+
+# PR demo with a dev server (for web UI changes):
+agentreel --pr 123 --start "npm run dev"
+
 # CLI demo:
 agentreel --cmd "npx my-cli-tool"
 
 # Browser demo:
 agentreel --url http://localhost:3000
-
-# With context for smarter demo planning:
-agentreel --cmd "npx my-tool" --prompt "A CLI that manages cron jobs"
 ```
 
-## How it works
+## Modes
+
+### PR demo (`--pr`)
+
+Point it at a pull request. It fetches the diff, description, and README from GitHub, then AI plans and records a demo showing what the PR actually does.
 
-1. You provide a CLI command or URL
-2. AI plans and executes a demo (terminal or browser)
-3. AI picks the 3-4 best highlight moments
-4. Renders a polished video with music, transitions, and overlays
-5. Prompts you to share on Twitter
+- **1920x1080 landscape** — chapter-based walkthrough
+- **4-6 chapters**, 12s each — full command + output flows
+- No music, no marketing overlays — just the real demo
+- Great for attaching to PRs so reviewers can see the change in action
 
-## What you get
+Requires [`gh` CLI](https://cli.github.com) to be installed and authenticated.
 
-A 15-20 second 1080x1080 video with:
-- **Title card** with your project name
-- **Highlight clips** — terminal or browser window on animated gradient
-- **Text overlays** — bold captions that work on mute
-- **Cursor + typing** — looks like someone's actually using it
-- **Background music** with fade in/out
-- **End CTA** — install command + URL
+### Marketing reel (`--cmd` / `--url`)
 
-Ready for Twitter/X, LinkedIn, Reels.
+The original mode — creates a short, polished clip for social media.
 
-## Supports
+- **1080x1080 square** — optimized for Twitter/X, LinkedIn, Reels
+- **3-4 highlight snippets**, 4.5s each — the best moments
+- Music, animated transitions, text overlays, cursor animations
+- Prompts you to share on Twitter
 
-- **CLI demos** — records your tool in a terminal, shows the highlights
-- **Browser demos** — records your web app via Playwright, shows the key moments
+## How it works
+
+1. **PR mode**: Fetches PR diff + README from GitHub, AI decides CLI or browser demo, plans steps that show the actual changes
+2. **Manual mode**: You provide a CLI command or URL, AI plans an impressive demo
+3. AI executes the demo (terminal PTY or Playwright browser)
+4. AI picks the best moments as highlights
+5. Renders video with Remotion
+
+## Flags
+
+```
+    --pr <ref>          PR number, owner/repo#N, or full GitHub URL
+    --start <cmd>       command to start a dev server (for browser PR demos)
+-c, --cmd <command>     CLI command to demo
+-u, --url <url>         URL to demo (browser mode)
+-t, --title <text>      video title
+-o, --output <file>     output file (default: agentreel.mp4)
+-a, --auth <file>       Playwright storage state (cookies/auth) for browser demos
+-g, --guidelines <text> guidelines for highlight generation
+    --music <file>      path to background music mp3
+    --no-share          skip the share prompt
+```
 
 ## Requirements
 
 - Node.js 18+
 - Python 3.10+
 - Claude CLI (`claude`) — used to plan demo sequences
+- `gh` CLI — required for `--pr` mode
 
 ## Credits
 

package/bin/agentreel.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { readFileSync, statSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { tmpdir } from "node:os";
@@ -25,7 +25,8 @@ function parseArgs() {
     }
     if (arg === "--cmd" || arg === "-c") flags.cmd = args[++i];
     else if (arg === "--url" || arg === "-u") flags.url = args[++i];
-    else if (arg === "--prompt" || arg === "-p") flags.prompt = args[++i];
+    else if (arg === "--pr") flags.pr = args[++i];
+    else if (arg === "--start") flags.start = args[++i];
     else if (arg === "--title" || arg === "-t") flags.title = args[++i];
     else if (arg === "--output" || arg === "-o") flags.output = args[++i];
     else if (arg === "--music") flags.music = args[++i];
@@ -40,13 +41,16 @@ function printUsage() {
   console.log(`agentreel — Turn your web apps and CLIs into viral clips
 
 Usage:
+  agentreel --pr 123                             # demo a PR (reads context from GitHub)
+  agentreel --pr owner/repo#123                  # demo a PR (explicit repo)
   agentreel --cmd "npx my-cli-tool"              # CLI demo
   agentreel --url http://localhost:3000           # browser demo
 
 Flags:
+      --pr <ref>          PR number, owner/repo#N, or full GitHub URL
+      --start <cmd>       command to start a dev server (for browser PR demos)
   -c, --cmd <command>     CLI command to demo
   -u, --url <url>         URL to demo (browser mode)
-  -p, --prompt <text>     description of what the tool does
   -t, --title <text>      video title
   -o, --output <file>     output file (default: agentreel.mp4)
   -a, --auth <file>       Playwright storage state (cookies/auth) for browser demos
@@ -326,29 +330,7 @@ async function renderVideo(props, output, musicPath) {
   console.error(`\nDone: ${output} (${Math.round(size / 1024)} KB)`);
 }
 
-// ── Upload + Share ──────────────────────────────────────────
-
-// Video upload placeholder — will add agentreel.dev hosting later
-async function uploadVideo(_filePath) {
-  return null;
-}
-
-function openShareURL(videoURL, text) {
-  const tweetText = encodeURIComponent(text);
-  const encodedURL = encodeURIComponent(videoURL);
-  const intentURL = `https://twitter.com/intent/tweet?text=${tweetText}&url=${encodedURL}`;
-
-  console.error(`\n  Share: ${videoURL}`);
-  console.error(`  Tweet: ${intentURL}\n`);
-
-  // Open in browser
-  const cmd = process.platform === "darwin" ? "open" : "xdg-open";
-  try {
-    execFileSync(cmd, [intentURL], { stdio: "ignore" });
-  } catch {
-    console.error("  (Could not open browser — copy the link above)");
-  }
-}
+// ── Share ───────────────────────────────────────────────────
 
 function askYesNo(question) {
   return new Promise((resolve) => {
@@ -383,20 +365,150 @@ async function shareFlow(outputPath, title, prompt) {
   }
 }
 
-// ── Auto-describe ──────────────────────────────────────────
+// ── PR Context ─────────────────────────────────────────────
 
-function autoDescribe(cmd, url) {
-  const target = cmd || url;
+function fetchPRContext(prRef) {
   try {
-    const result = execFileSync("claude", [
-      "-p",
-      `Describe what this tool/app does in one short sentence (under 10 words). No quotes, no period. Just the description.\n\n${target}`,
-      "--output-format", "text",
-    ], { encoding: "utf-8", timeout: 30000, stdio: ["ignore", "pipe", "ignore"] });
-    const desc = result.trim();
-    if (desc && desc.length < 100) return desc;
-  } catch { /* fall through */ }
-  return cmd ? cmd.split(/\s+/).pop() : "Web app demo";
+    execFileSync("gh", ["--version"], { stdio: "ignore" });
+  } catch {
+    console.error("Error: `gh` CLI is required for --pr mode. Install it from https://cli.github.com");
+    process.exit(1);
+  }
+
+  const prJson = execFileSync("gh", [
+    "pr", "view", String(prRef),
+    "--json", "title,body,headRefName,baseRefName,url,number",
+  ], { encoding: "utf-8", timeout: 30000 });
+  const pr = JSON.parse(prJson);
+
+  let diff = "";
+  try {
+    diff = execFileSync("gh", ["pr", "diff", String(prRef)], {
+      encoding: "utf-8", timeout: 30000,
+    });
+  } catch (e) {
+    console.error(`  Warning: could not fetch PR diff: ${e.message}`);
+  }
+
+  // Read README from cwd (the agent already has the repo checked out)
+  let readme = "";
+  for (const name of ["README.md", "readme.md", "README", "README.rst"]) {
+    const p = join(process.cwd(), name);
+    if (existsSync(p)) {
+      readme = readFileSync(p, "utf-8");
+      break;
+    }
+  }
+
+  return { ...pr, diff, readme };
+}
+
+function planDemoFromPR(prContext, guidelines) {
+  const guidelinesBlock = guidelines
+    ? `\nAdditional guidelines: ${guidelines}`
+    : "";
+
+  const prompt = `You are planning a demo for a Pull Request. Your job is to decide whether this is a CLI or browser demo, and provide the details needed to record it.
+
+PR Title: ${prContext.title}
+PR Description: ${prContext.body || "(no description)"}
+
+Diff (truncated):
+${prContext.diff.slice(0, 8000)}
+
+README (truncated):
+${prContext.readme.slice(0, 3000)}${guidelinesBlock}
+
+Return a JSON object with these fields:
+{
+  "type": "cli" or "browser",
+  "command": "the command to run" (for CLI demos, e.g. "npx my-tool --help") or null,
+  "url": "http://localhost:3000/relevant-page" (for browser demos) or null,
+  "description": "one-sentence summary of what the PR does",
+  "title": "short video title (2-4 words)",
+  "guidelines": "specific instructions for the demo recorder about what steps to show and what to focus on"
+}
+
+Rules:
+- If the PR changes a CLI tool, script, or backend logic that can be demonstrated in a terminal, use "cli".
+- If the PR changes a web UI, frontend, or something best shown in a browser, use "browser".
+- The "guidelines" field should tell the demo recorder exactly what to demonstrate — the specific feature or fix from this PR.
+- The demo should show the actual changes working honestly, not market the product.
+- Return ONLY the JSON object, no markdown fences.`;
+
+  const result = execFileSync("claude", ["-p", prompt, "--output-format", "text"], {
+    encoding: "utf-8",
+    timeout: 60000,
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+
+  // Strip markdown fences if present
+  let text = result;
+  if (text.includes("```")) {
+    const parts = text.split("```");
+    for (let part of parts) {
+      part = part.trim();
+      if (part.startsWith("json")) part = part.slice(4).trim();
+      if (part.startsWith("{")) { text = part; break; }
+    }
+  }
+
+  return JSON.parse(text);
+}
+
+// ── Dev Server ─────────────────────────────────────────────
+
+function startDevServer(command) {
+  console.error(`  Starting dev server: ${command}`);
+  const proc = spawn("sh", ["-c", command], {
+    stdio: ["ignore", "pipe", "pipe"],
+    detached: true,
+  });
+
+  // Wait for server to be ready (look for common ready signals in output)
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      console.error("  Dev server ready (timeout — assuming started)");
+      resolve(proc);
+    }, 30000);
+
+    const onData = (data) => {
+      const text = data.toString();
+      if (/localhost|ready|started|listening|compiled/i.test(text)) {
+        clearTimeout(timeout);
+        // Give it a moment to fully start
+        setTimeout(() => {
+          console.error("  Dev server ready");
+          resolve(proc);
+        }, 2000);
+      }
+    };
+
+    proc.stdout.on("data", onData);
+    proc.stderr.on("data", onData);
+
+    proc.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(new Error(`Dev server failed to start: ${err.message}`));
+    });
+
+    proc.on("exit", (code) => {
+      clearTimeout(timeout);
+      if (code !== null && code !== 0) {
+        reject(new Error(`Dev server exited with code ${code}`));
+      }
+    });
+  });
+}
+
+function stopDevServer(proc) {
+  if (!proc || proc.killed) return;
+  try {
+    // Kill the process group (detached process + children)
+    process.kill(-proc.pid, "SIGTERM");
+  } catch {
+    try { proc.kill("SIGTERM"); } catch { /* already dead */ }
+  }
 }
 
 // ── Main ────────────────────────────────────────────────────
@@ -406,83 +518,152 @@ async function main() {
   const output = flags.output || "agentreel.mp4";
   const noShare = flags.noShare;
 
-  let demoCmd = flags.cmd;
-  let demoURL = flags.url;
-  let prompt = flags.prompt;
-
-  // Auto-generate description if not provided
-  if (!prompt) {
-    console.error("Generating description...");
-    prompt = autoDescribe(demoCmd, demoURL);
-    console.error(`  "${prompt}"`);
-  }
-
-  if (!demoCmd && !demoURL) {
-    console.error("Please provide --cmd or --url.\n");
+  if (!flags.cmd && !flags.url && !flags.pr) {
+    console.error("Please provide --pr, --cmd, or --url.\n");
     printUsage();
     process.exit(1);
   }
 
-  let videoTitle = flags.title || demoCmd || demoURL;
+  // ── PR mode ──────────────────────────────────────────────
+  if (flags.pr) {
+    console.error("Fetching PR context...");
+    const prContext = fetchPRContext(flags.pr);
+    console.error(`  PR #${prContext.number}: ${prContext.title}`);
+
+    console.error("Planning demo...");
+    const plan = planDemoFromPR(prContext, flags.guidelines);
+    console.error(`  Type: ${plan.type}, "${plan.description}"`);
+
+    const videoTitle = flags.title || plan.title || prContext.title;
+    const description = plan.description;
+    // Prepend "demo" to guidelines so downstream scripts know to use chapter-based extraction
+    const demoGuidelines = `[demo] ${plan.guidelines || ""}`.trim();
+
+    if (plan.type === "browser") {
+      const url = plan.url || "http://localhost:3000";
+      let serverProc = null;
+
+      try {
+        if (flags.start) {
+          serverProc = await startDevServer(flags.start);
+        }
+
+        ensureBrowserDeps();
+        console.error("Step 1/3: Recording browser demo...");
+        const videoPath = recordBrowser(url, demoGuidelines, flags.auth, demoGuidelines);
+
+        const publicDir = join(ROOT, "public");
+        if (!existsSync(publicDir)) mkdirSync(publicDir, { recursive: true });
+        copyFileSync(videoPath, join(publicDir, "browser-demo.mp4"));
+
+        console.error("Step 2/3: Building highlights...");
+        const clicksPath = videoPath.replace(".mp4", "-clicks.json");
+        let allClicks = [];
+        if (existsSync(clicksPath)) {
+          allClicks = JSON.parse(readFileSync(clicksPath, "utf-8"));
+          console.error(`  ${allClicks.length} clicks captured`);
+        }
+        const highlights = buildBrowserHighlights(allClicks, videoPath, demoGuidelines, demoGuidelines);
+
+        console.error("Step 3/3: Rendering video...");
+        await renderVideo({
+          title: videoTitle,
+          subtitle: description,
+          highlights,
+          endText: prContext.title,
+          endUrl: prContext.url,
+          mode: "demo",
+        }, output, flags.music);
+      } finally {
+        stopDevServer(serverProc);
+      }
+    } else {
+      // CLI demo
+      if (!plan.command) {
+        console.error("Error: Claude could not determine a command to demo for this PR.");
+        process.exit(1);
+      }
+
+      console.error("Step 1/3: Recording CLI demo...");
+      const castPath = recordCLI(plan.command, process.cwd(), description, demoGuidelines);
+
+      console.error("Step 2/3: Extracting highlights...");
+      const highlightsPath = extractHighlightsFromCast(castPath, description, demoGuidelines);
+      const highlights = JSON.parse(readFileSync(highlightsPath, "utf-8"));
+      console.error(`  ${highlights.length} highlights extracted`);
+
+      console.error("Step 3/3: Rendering video...");
+      await renderVideo({
+        title: videoTitle,
+        subtitle: description,
+        highlights,
+        endText: plan.command,
+        endUrl: prContext.url,
+        mode: "demo",
+      }, output, flags.music);
+    }
 
-  if (demoCmd) {
+    if (!noShare) {
+      await shareFlow(resolve(output), videoTitle, description);
+    }
+    return;
+  }
+
+  // ── Manual modes (--cmd / --url) ─────────────────────────
+  let videoTitle = flags.title || flags.cmd || flags.url;
+
+  if (flags.cmd) {
     console.error("Step 1/3: Recording CLI demo...");
-    const castPath = recordCLI(demoCmd, process.cwd(), prompt, flags.guidelines);
+    const castPath = recordCLI(flags.cmd, process.cwd(), flags.cmd, flags.guidelines);
 
     console.error("Step 2/3: Extracting highlights...");
-    const highlightsPath = extractHighlightsFromCast(castPath, prompt, flags.guidelines);
+    const highlightsPath = extractHighlightsFromCast(castPath, flags.cmd, flags.guidelines);
     const highlights = JSON.parse(readFileSync(highlightsPath, "utf-8"));
     console.error(`  ${highlights.length} highlights extracted`);
 
     console.error("Step 3/3: Rendering video...");
     await renderVideo({
       title: videoTitle,
-      subtitle: prompt,
       highlights,
-      endText: demoCmd,
+      endText: flags.cmd,
     }, output, flags.music);
 
     if (!noShare) {
-      await shareFlow(resolve(output), videoTitle, prompt);
+      await shareFlow(resolve(output), videoTitle, flags.cmd);
     }
     return;
   }
 
-  if (demoURL) {
-    const task = prompt || "Explore the main features of this app";
+  if (flags.url) {
+    const task = "Explore the main features of this app";
 
     ensureBrowserDeps();
     console.error("Step 1/3: Recording browser demo...");
-    const videoPath = recordBrowser(demoURL, task, flags.auth, flags.guidelines);
+    const videoPath = recordBrowser(flags.url, task, flags.auth, flags.guidelines);
 
-    // Copy video to Remotion public dir so it can be served
     const publicDir = join(ROOT, "public");
     if (!existsSync(publicDir)) mkdirSync(publicDir, { recursive: true });
     copyFileSync(videoPath, join(publicDir, "browser-demo.mp4"));
 
     console.error("Step 2/3: Building highlights...");
-
-    // Read click data — this is the primary signal for highlights
     const clicksPath = videoPath.replace(".mp4", "-clicks.json");
     let allClicks = [];
     if (existsSync(clicksPath)) {
       allClicks = JSON.parse(readFileSync(clicksPath, "utf-8"));
       console.error(`  ${allClicks.length} clicks captured`);
     }
-
     const highlights = buildBrowserHighlights(allClicks, videoPath, task, flags.guidelines);
 
     console.error("Step 3/3: Rendering video...");
     await renderVideo({
       title: videoTitle,
-      subtitle: prompt,
       highlights,
-      endText: demoURL,
-      endUrl: demoURL,
+      endText: flags.url,
+      endUrl: flags.url,
     }, output, flags.music);
 
     if (!noShare) {
-      await shareFlow(resolve(output), videoTitle, prompt);
+      await shareFlow(resolve(output), videoTitle, flags.url);
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentreel",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "description": "Turn your web apps and CLIs into viral clips",
   "bin": {
     "agentreel": "./bin/agentreel.mjs"

package/scripts/cli_demo.py

@@ -198,7 +198,7 @@ def record_demo(steps: list[dict], workdir: str, output_path: str):
 
 
 def extract_highlights(cast_path: str, context: str, guidelines: str = "") -> list[dict]:
-    """Ask Claude to pick 3-4 highlight moments from the recorded session."""
+    """Ask Claude to pick highlight moments from the recorded session."""
     # Read the asciicast and strip to just the text content
     lines_output = []
     with open(cast_path) as f:
@@ -218,7 +218,29 @@ def extract_highlights(cast_path: str, context: str, guidelines: str = "") -> li
 
     guidelines_block = f"\n\nAdditional guidelines: {guidelines}" if guidelines else ""
 
-    prompt = f"""You are creating a highlights reel for a CLI tool demo video. Here is the full terminal output:
+    # Demo mode: more chapters, more lines, show full flows
+    is_demo = "demo" in guidelines.lower() if guidelines else False
+
+    if is_demo:
+        prompt = f"""You are creating chapter-based highlights for a demo walkthrough video. Here is the full terminal output:
+
+---
+{clean[:6000]}
+---
+
+Context: {context}{guidelines_block}
+
+Create 4-6 chapters that walk through the full demo. Each chapter shows a complete command and its output. For each chapter, return:
+- "label": chapter name (1-3 words) like "Setup", "Run Command", "View Results", "Verify"
+- "lines": array of objects, each with "text" (string), and optionally "color" (hex), "bold" (bool), "dim" (bool), "isPrompt" (bool if it's a shell command)
+
+Each chapter should have 12-20 lines. Show the COMPLETE command and output for each step.
+Include the prompt line (isPrompt: true) followed by the actual output.
+Use these colors: green="#50fa7b", yellow="#f1fa8c", purple="#bd93f9", red="#ff5555", dim="#6272a4", white="#f8f8f2"
+
+Return ONLY a JSON array. No markdown fences."""
+    else:
+        prompt = f"""You are creating a highlights reel for a CLI tool demo video. Here is the full terminal output:
 
 ---
 {clean[:3000]}