EtienneLescot · Oct 11, 2026 · Oct 11, 2026
@@ -64,7 +64,7 @@ openscreen export demo.openscreen -o demo.mp4 --json
 
 See the [CLI reference](https://getopenscreen.com/docs/cli/).
 
-### Let your coding agent make the demo
+### Let your coding agent ship the feature with its video
 
 Give Claude Code, Codex or Cursor OpenScreen's MCP tools, and the skill that
 teaches the whole job:
@@ -74,11 +74,12 @@ claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Opensc
 npx skills add getopenscreen/openscreen --skill openscreen-demo
 ```
 
-Then ask: *"Make a demo video of this feature with OpenScreen."* The agent plans
-the storyboard, records the app, edits the take with OpenScreen's own editing
-tools, exports the MP4, checks it frame by frame, and drafts the post for X,
-which it publishes only once you say yes. The executable on Windows and Linux,
-and the other clients, are in [AI editing](https://getopenscreen.com/docs/ai-editing/#letting-an-agent-make-the-whole-video).
+Then ask: *"Add a video of this change to the PR."* The agent plans the
+storyboard, records the app, edits the take with OpenScreen's own editing tools,
+exports the MP4, checks it frame by frame, and attaches it to the pull request,
+where reviewers watch it in place. Ask for a launch demo instead and it drafts a
+post for X, which it publishes only once you say yes. The executable on Windows
+and Linux, and the other clients, are in [AI editing](https://getopenscreen.com/docs/ai-editing/#letting-an-agent-make-the-whole-video).
 
 ## Installation
 

@@ -1,11 +1,14 @@
 ---
 name: openscreen-demo
-description: Make a polished product demo video of an app or a feature with OpenScreen's MCP tools, from storyboard to recording, editing, export and a post on X. Use when the user asks for a demo, a demo video, a screen recording, a product video, a launch clip, or a video for X/Twitter, LinkedIn, a README or a pull request.
+description: Make a polished video of an app or a feature with OpenScreen's MCP tools, from storyboard to recording, editing and export, then either attach it to a pull request or draft a post on X. Use when the user asks for a demo, a demo video, a screen recording, a product video, a launch clip, a video for X/Twitter, LinkedIn or a README, or to show a change in a pull request ("add a video to the PR", "show the feature to reviewers").
 ---
 
 # Make a demo video with OpenScreen
 
-You produce a short MP4 (20 to 60 s, 1080p, 60 fps) that shows one feature, zooms on the action and carries its message in on-screen callouts, then a post ready for X. You do the whole job through OpenScreen's MCP tools: record, edit, export, look. **Nothing is ever posted without the user's explicit yes.**
+You produce a short MP4 that shows one feature, zooms on the action and carries its message in on-screen callouts. You do the whole job through OpenScreen's MCP tools: record, edit, export, look. It ends one of two ways:
+
+- **A pull request video:** 10 to 30 s, showing the change a pull request makes, attached to that pull request so reviewers watch it in place (step 8).
+- **A launch demo:** 20 to 60 s, 1080p, with a post drafted for X (step 9). **Nothing is ever posted without the user's explicit yes.**
 
 ## 1. Connect OpenScreen
 
@@ -31,8 +34,8 @@ Then ask the user to start a new session so the tools load. If the app is not in
 Write a storyboard and show it to the user in a few lines, then carry on unless they object.
 
 - **One message.** What should a viewer remember after 3 seconds? The first beat shows the result, not a setup screen.
-- **3 to 6 beats.** Each beat is one action and one callout of 6 words or fewer.
-- **20 to 60 seconds.** X autoplays muted, so the callouts carry the story, not a voice.
+- **Launch demo: 3 to 6 beats, 20 to 60 seconds.** Each beat is one action and one callout of 6 words or fewer. X autoplays muted, so the callouts carry the story, not a voice.
+- **Pull request video: 1 to 3 beats, 10 to 30 seconds.** Show what the change does, not the whole product: the new behavior, or the bug no longer happening. The pull request text explains the rest, so one short callout per beat is enough.
 - **Realistic data.** Seed the app with believable content. No real customer data, secrets, tokens or personal notifications on screen.
 
 ## 3. Set the stage
@@ -72,15 +75,36 @@ Keep the rest as it is: the background, padding, shadow and cursor style are cho
 
 ## 7. Export and review
 
-1. `exportVideo` with the `projectId` and a path such as `demo/demo.mp4`.
+1. `exportVideo` with the `projectId` and a path such as `demo/demo.mp4`. For a pull request video, pass `quality: "medium"` (720p) to keep the file small.
 2. `getFrames` with the `projectId`, at the ruler seconds of your beats.
 3. Check every frame:
    - Is each callout readable and clear of the action?
    - Is each zoom on the thing that changes?
    - Are there black frames, cut-off text or a leftover setup screen?
 4. Fix the project and export again until it holds.
 
-## 8. Post on X
+Never commit the video to the repository: it goes into the pull request or the post, not the code.
+
+## 8. Attach it to the pull request
+
+Only to a pull request the user asked for a video on, or one you open for them in this task.
+
+1. **Check the size.** GitHub takes videos up to 10 MB in a repository on a free plan, 100 MB on a paid one. Over the limit, cut or speed up a beat and export again.
+2. **Write the text around it** in a file, say `demo/pr-video.md`: one line saying what the video shows, then the video alone in its own paragraph, so GitHub shows a player and not a link:
+
+   ```markdown
+   **Demo:** the export dialog now remembers the last format.
+
+   ![](demo/pr-video.mp4)
+   ```
+
+3. **Attach it with `gh`**, version 2.99.0 or later (`gh --version`). `gh` uploads the file and puts its URL in place of the path. You need push access to the repository.
+   - On an existing pull request, as a comment: `gh pr comment <number> --body-file demo/pr-video.md --attach demo/pr-video.mp4`
+   - On a pull request you are opening: put the same two lines in its body, and pass `--attach demo/pr-video.mp4` to `gh pr create`.
+4. **With an older `gh`,** ask the user to update it. **On GitHub Enterprise Server,** where `gh` cannot attach files at all, skip `--attach`. In both cases, use a browser tool that can attach a file to the comment box on the pull request's page, or else give the user the file and the text to drop in themselves.
+5. Report the comment's or the pull request's URL.
+
+## 9. Post on X
 
 1. **Write the post.** At most 280 characters: the hook first, then what it does, then the link if there is one. One or two hashtags at most.
 2. **Check X's limits.** The video must be an MP4 of at most 2 min 20 s and 512 MB for an account without Premium. The export fits.
@@ -93,3 +117,4 @@ Keep the rest as it is: the background, padding, shadow and cursor style are cho
 - **`The recording did not start`:** the window title did not match, or capture is not permitted. Check `listSources` and the permissions in step 1.
 - **No cursor in the video:** the app was driven by a script. See step 4.
 - **No zoom on an early click:** the first 2.5 s stay wide on purpose. Start the first action after that.
+- **`unknown flag: --attach`:** `gh` is older than 2.99.0. See step 8.
@@ -83,4 +83,4 @@ The executable on each system is listed in [Running the CLI](./cli.md#running-th
 - **No port, no token, no setting.** The agent starts the process itself, with your rights, as it would run `openscreen record`. So it can record your screen and edit without the **Project edits** switch.
 - **Each take becomes a new project** in your project list, with a zoom on each recorded click, as a recording made in the app. Do not edit it in the editor while the agent is still working on it: the editor keeps its own copy.
 - **A take driven by a script** (Playwright, for example) never moves the screen pointer. The agent hands OpenScreen its own log of the actions with `setPointerTrack`, and the video gets a cursor and its zooms all the same.
-- **The `openscreen-demo` skill** teaches an agent the whole job, from the storyboard to a post on X that it publishes only once you say yes. Add it with `npx skills add getopenscreen/openscreen --skill openscreen-demo`. The recipe is [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
+- **The `openscreen-demo` skill** teaches an agent the whole job, from the storyboard to the finished video. It then attaches the video to a pull request, so reviewers watch the change in place, or drafts a post on X that it publishes only once you say yes. Add it with `npx skills add getopenscreen/openscreen --skill openscreen-demo`. The recipe is [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
@@ -83,4 +83,4 @@ Die ausführbare Datei für jedes System steht unter [Die CLI ausführen](./cli.
 - **Kein Port, kein Token, keine Einstellung.** Der Agent startet den Prozess selbst, mit deinen Rechten, so wie er `openscreen record` ausführen würde. Deshalb kann er deinen Bildschirm aufnehmen und bearbeiten, ohne den Schalter **Project edits**.
 - **Jeder Take wird zu einem neuen Projekt** in deiner Projektliste, mit einem Zoom auf jeden aufgezeichneten Klick, wie eine in der App gemachte Aufnahme. Bearbeite es nicht im Editor, solange der Agent noch daran arbeitet: Der Editor hält seine eigene Kopie.
 - **Ein per Skript gesteuerter Take** (zum Beispiel mit Playwright) bewegt nie den Zeiger auf dem Bildschirm. Der Agent übergibt OpenScreen mit `setPointerTrack` sein eigenes Protokoll der Aktionen, und das Video bekommt trotzdem einen Cursor und dessen Zooms.
-- **Der Skill `openscreen-demo`** bringt einem Agenten die ganze Arbeit bei, vom Storyboard bis zu einem Post auf X, den er erst veröffentlicht, wenn du Ja sagst. Füge ihn mit `npx skills add getopenscreen/openscreen --skill openscreen-demo` hinzu. Das Rezept ist [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
+- **Der Skill `openscreen-demo`** bringt einem Agenten die ganze Arbeit bei, vom Storyboard bis zum fertigen Video. Danach hängt er das Video an einen Pull Request, damit die Reviewer die Änderung direkt dort sehen, oder entwirft einen Post auf X, den er erst veröffentlicht, wenn du Ja sagst. Füge ihn mit `npx skills add getopenscreen/openscreen --skill openscreen-demo` hinzu. Das Rezept ist [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
@@ -83,4 +83,4 @@ El ejecutable de cada sistema aparece en [Ejecutar la CLI](./cli.md#running-the-
 - **Sin puerto, sin token, sin ajuste.** El agente inicia el proceso él mismo, con tus permisos, como ejecutaría `openscreen record`. Así puede grabar tu pantalla y editar sin el interruptor **Ediciones del proyecto**.
 - **Cada toma se convierte en un proyecto nuevo** en tu lista de proyectos, con un zoom en cada clic grabado, como una grabación hecha en la app. No lo edites en el editor mientras el agente siga trabajando en él: el editor conserva su propia copia.
 - **Una toma controlada por un script** (Playwright, por ejemplo) nunca mueve el puntero de la pantalla. El agente le pasa a OpenScreen su propio registro de las acciones con `setPointerTrack`, y el video obtiene igualmente un cursor y sus zooms.
-- **La skill `openscreen-demo`** le enseña a un agente todo el trabajo, desde el storyboard hasta un post en X que solo publica cuando dices que sí. Agrégala con `npx skills add getopenscreen/openscreen --skill openscreen-demo`. La receta es [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
+- **La skill `openscreen-demo`** le enseña a un agente todo el trabajo, desde el storyboard hasta el video terminado. Después adjunta el video a un pull request, para que los revisores vean el cambio ahí mismo, o redacta un post en X que solo publica cuando dices que sí. Agrégala con `npx skills add getopenscreen/openscreen --skill openscreen-demo`. La receta es [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
@@ -83,4 +83,4 @@ L'exécutable de chaque système est indiqué dans [Lancer la CLI](./cli.md#runn
 - **Ni port, ni jeton, ni réglage.** L'agent lance lui-même le processus, avec vos droits, comme il lancerait `openscreen record`. Il peut donc enregistrer votre écran et faire des modifications sans l'interrupteur **Modifications du projet**.
 - **Chaque prise devient un nouveau projet** dans votre liste de projets, avec un zoom sur chaque clic enregistré, comme un enregistrement fait dans l'application. Ne le modifiez pas dans l'éditeur tant que l'agent y travaille encore : l'éditeur garde sa propre copie.
 - **Une prise pilotée par un script** (Playwright, par exemple) ne déplace jamais le pointeur de l'écran. L'agent transmet à OpenScreen son propre journal des actions avec `setPointerTrack`, et la vidéo a malgré tout un curseur et ses zooms.
-- **La skill `openscreen-demo`** enseigne à un agent tout le travail, du storyboard jusqu'à un post sur X qu'il ne publie qu'une fois que vous avez dit oui. Ajoutez-la avec `npx skills add getopenscreen/openscreen --skill openscreen-demo`. La recette est [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
+- **La skill `openscreen-demo`** enseigne à un agent tout le travail, du storyboard jusqu'à la vidéo finie. Il joint ensuite la vidéo à une pull request, pour que les relecteurs voient le changement sur place, ou rédige un post sur X qu'il ne publie qu'une fois que vous avez dit oui. Ajoutez-la avec `npx skills add getopenscreen/openscreen --skill openscreen-demo`. La recette est [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
@@ -83,4 +83,4 @@ codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscr
 - **ポートも、トークンも、設定も不要。** エージェントは、`openscreen record` を実行するときと同じように、あなたの権限でプロセスを自分で起動します。そのため、**プロジェクトの編集**スイッチなしで、画面を録画し、編集できます。
 - **テイクはそれぞれ新しいプロジェクトになり**、プロジェクト一覧に表示されます。アプリで作った録画と同じく、記録された各クリックにズームが付きます。エージェントがまだ作業している間は、エディターで編集しないでください。エディターは独自のコピーを保持しています。
 - **スクリプトで操作するテイク**（たとえば Playwright）では、画面のポインターはまったく動きません。エージェントが `setPointerTrack` で自分の操作ログを OpenScreen に渡せば、動画には同じようにカーソルとそのズームが付きます。
-- **`openscreen-demo` スキル**は、絵コンテから X への投稿まで、作業全体をエージェントに教えます。投稿は、あなたが了承してはじめて公開されます。`npx skills add getopenscreen/openscreen --skill openscreen-demo` で追加します。手順は [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md) にあります。
+- **`openscreen-demo` スキル**は、絵コンテから完成した動画まで、作業全体をエージェントに教えます。そのあとエージェントは、レビュアーがその場で変更を確認できるよう動画をプルリクエストに添付するか、X への投稿を下書きします。投稿は、あなたが了承してはじめて公開されます。`npx skills add getopenscreen/openscreen --skill openscreen-demo` で追加します。手順は [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md) にあります。
@@ -83,4 +83,4 @@ O executável de cada sistema está listado em [Como executar a CLI](./cli.md#ru
 - **Sem porta, sem token, sem configuração.** O agente inicia o processo por conta própria, com as suas permissões, como faria ao rodar `openscreen record`. Por isso ele pode gravar a sua tela e editar sem o interruptor **Edições do projeto**.
 - **Cada tomada vira um novo projeto** na sua lista de projetos, com um zoom em cada clique gravado, como uma gravação feita no app. Não o edite no editor enquanto o agente ainda estiver trabalhando nele: o editor mantém a própria cópia.
 - **Uma tomada conduzida por um script** (o Playwright, por exemplo) nunca move o ponteiro da tela. O agente passa ao OpenScreen o próprio registro das ações com `setPointerTrack`, e o vídeo ganha um cursor e seus zooms do mesmo jeito.
-- **A skill `openscreen-demo`** ensina a um agente o trabalho inteiro, do storyboard até um post no X que ele só publica depois que você disser sim. Adicione-a com `npx skills add getopenscreen/openscreen --skill openscreen-demo`. A receita é [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
+- **A skill `openscreen-demo`** ensina a um agente o trabalho inteiro, do storyboard até o vídeo pronto. Depois ele anexa o vídeo a um pull request, para que os revisores vejam a mudança ali mesmo, ou redige um post no X que só publica depois que você disser sim. Adicione-a com `npx skills add getopenscreen/openscreen --skill openscreen-demo`. A receita é [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md).
@@ -83,4 +83,4 @@ codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscr
 - **无需端口、令牌或设置**。AI 代理以你的权限自行启动进程，就像它运行 `openscreen record` 一样。因此，它无需**项目编辑**开关，就能录制你的屏幕并进行编辑。
 - **每次录制都会成为一个新项目**，出现在你的项目列表中，并且与在应用中录制的内容一样，在每次录制下来的点击处添加缩放。在 AI 代理仍在处理它时，不要在编辑器中编辑它：编辑器会保留自己的副本。
 - **由脚本驱动的录制**（例如 Playwright）永远不会移动屏幕指针。AI 代理通过 `setPointerTrack` 把它自己的操作日志交给 OpenScreen，视频照样会有光标及其缩放。
-- **`openscreen-demo` 技能**会教 AI 代理完成整个工作，从分镜脚本到 X 上的帖子，而且只有在你同意之后，它才会发布这条帖子。使用 `npx skills add getopenscreen/openscreen --skill openscreen-demo` 添加它。具体步骤见 [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md)。
+- **`openscreen-demo` 技能**会教 AI 代理完成整个工作，从分镜脚本到成品视频。之后，它会把视频附加到拉取请求中，让审阅者直接在那里看到改动；或者起草一条 X 帖子，而且只有在你同意之后，它才会发布这条帖子。使用 `npx skills add getopenscreen/openscreen --skill openscreen-demo` 添加它。具体步骤见 [`skills/openscreen-demo/SKILL.md`](https://github.com/getopenscreen/openscreen/blob/main/skills/openscreen-demo/SKILL.md)。