From bff8fba9b283d9c5119e7dc4099a86b1a46aa50c Mon Sep 17 00:00:00 2001 From: EtienneLescot Date: Mon, 12 Oct 2026 11:17:07 +0200 Subject: [PATCH 1/2] docs: one line to paste into Claude Code, and a skill that sets OpenScreen up The skill's first step now installs OpenScreen when it is missing or too old to serve MCP (from the latest official release, once the user agrees), adds the MCP server, and hands over to the next session through openscreen-demo-plan.md, the one restart an agent cannot avoid. The README and the AI editing page (every locale) lead with the line to paste, the manual commands after it. --- README.md | 14 ++++++++--- skills/openscreen-demo/SKILL.md | 25 ++++++++++++++----- website/docs/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ .../current/ai-editing.md | 8 ++++++ 10 files changed, 94 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index df1fae2609..ef31cfe087 100644 --- a/README.md +++ b/README.md @@ -65,15 +65,23 @@ See the [CLI reference](https://getopenscreen.com/docs/cli/). ### 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: +Paste this into Claude Code: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to add a video of this change to the PR. +``` + +The skill sets everything up: it installs OpenScreen if it is missing (once you +agree), connects its MCP server, then asks you to open a new session and say +*"continue the OpenScreen demo"*, the one step an agent cannot do for itself. +By hand, it is these two commands, with the executable of your system: ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp npx skills add getopenscreen/openscreen --skill openscreen-demo ``` -Then ask: *"Add a video of this change to the PR."* The agent plans the +From then on, 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 diff --git a/skills/openscreen-demo/SKILL.md b/skills/openscreen-demo/SKILL.md index a8dda473ee..53767a0724 100644 --- a/skills/openscreen-demo/SKILL.md +++ b/skills/openscreen-demo/SKILL.md @@ -1,6 +1,6 @@ --- name: openscreen-demo -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"). +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"). Also use to set OpenScreen up for an agent, and to continue an OpenScreen demo in a new session. --- # Make a demo video with OpenScreen @@ -10,9 +10,11 @@ You produce a short MP4 that shows one feature, zooms on the action and carries - **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 +## 1. Set up OpenScreen -You need the tools `startRecording`, `stopRecording`, `exportVideo` and `getFrames`. If they are missing, add OpenScreen's MCP server: it is the desktop app's own executable, started with `mcp`. +You need the tools `startRecording`, `stopRecording`, `exportVideo` and `getFrames`. If you have them, go to step 2. Otherwise set OpenScreen up, once per machine, doing only what is missing. + +**The app.** Its executable is the MCP server: | OS | Executable | |---|---| @@ -20,15 +22,26 @@ You need the tools `startRecording`, `stopRecording`, `exportVideo` and `getFram | macOS | `/Applications/Openscreen.app/Contents/MacOS/Openscreen` | | Linux | `openscreen` on the PATH, or the AppImage | +Run `"" help`: it must list `mcp`. If the app is missing, or too old to list it, offer to install the latest release, and do it only once the user agrees: + +1. Find the installer for this machine in the latest release of `getopenscreen/openscreen`: `gh release view --repo getopenscreen/openscreen --json assets`, or https://github.com/getopenscreen/openscreen/releases/latest. + - **macOS:** `Openscreen-macOS-Apple-Silicon-.dmg`, or `-Intel-` (check `uname -m`). Mount it, copy `Openscreen.app` to `/Applications`, unmount it. + - **Windows:** the `Openscreen.Setup..exe` installer, run with `/S /currentuser` for a silent install for the current user. + - **Linux:** the `.deb`, `.rpm` or `.pacman` for the distribution, or the `.AppImage` made executable. +2. Check `help` again. If even the latest release does not list `mcp`, this OpenScreen feature is not released yet: say so and stop. + +**The MCP server.** Add it to the agent, then the tools load in the next session: + - **Claude Code:** `claude mcp add openscreen -- "" mcp` - **Codex:** `codex mcp add openscreen -- "" mcp` - **Cursor and others:** a stdio server with the executable as `command` and `["mcp"]` as `args`. -Then ask the user to start a new session so the tools load. If the app is not installed, send the user to https://getopenscreen.com/download/ and stop there. - -- **macOS:** the app that runs the agent needs the Screen Recording permission. +**Permissions.** +- **macOS:** the app that runs the agent needs the Screen Recording permission, in System Settings → Privacy & Security. - **Linux:** the desktop's picker opens on every recording, and the user chooses the window. +**Hand over to the next session.** Write the user's request, and anything already decided, to `openscreen-demo-plan.md` in the working directory. Then ask the user to start a new session and say *continue the OpenScreen demo*. In that session, read the file and carry on from step 2. + ## 2. Plan before recording Write a storyboard and show it to the user in a few lines, then carry on unless they object. diff --git a/website/docs/ai-editing.md b/website/docs/ai-editing.md index 7eb381b240..4fba4c6e50 100644 --- a/website/docs/ai-editing.md +++ b/website/docs/ai-editing.md @@ -73,6 +73,14 @@ The tools are the ones the built-in agent uses, and they act on the project open The server above edits projects. To have an agent make a whole video on its own, from the recording to the export, add OpenScreen to it as a stdio server instead: the agent starts the app's own executable with `mcp`. It gets the same editing tools, plus `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo` and `getFrames`. +The quickest way is to paste this into Claude Code: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +The skill installs OpenScreen if it is missing, once you agree, and adds its MCP server. It then asks you to open a new session and say *continue the OpenScreen demo*: an agent only gets new tools in a new session. To set it up by hand instead: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md index 64379881ee..7b42508acf 100644 --- a/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/de/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ Die Werkzeuge sind die, die der eingebaute Agent nutzt, und sie wirken auf das i Der Server oben bearbeitet Projekte. Soll ein Agent ein ganzes Video selbstständig erstellen, von der Aufnahme bis zum Export, füge OpenScreen stattdessen als stdio-Server zum Agenten hinzu: Der Agent startet die eigene ausführbare Datei der App mit `mcp`. Er bekommt dieselben Bearbeitungswerkzeuge, dazu `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo` und `getFrames`. +Am schnellsten fügst du Folgendes in Claude Code ein: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +Der Skill installiert OpenScreen, falls es fehlt, sobald du zustimmst, und fügt seinen MCP-Server hinzu. Danach bittet er dich, eine neue Sitzung zu öffnen und *continue the OpenScreen demo* zu sagen: Ein Agent bekommt neue Werkzeuge nur in einer neuen Sitzung. So richtest du es stattdessen von Hand ein: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md index b9bd66e992..a56a010965 100644 --- a/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/es/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ Las herramientas son las que usa el agente integrado, y actúan sobre el proyect El servidor de arriba edita proyectos. Para que un agente haga un video completo por sí solo, desde la grabación hasta la exportación, agrega en cambio OpenScreen al agente como servidor stdio: el agente inicia el propio ejecutable de la app con `mcp`. Obtiene las mismas herramientas de edición, además de `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo` y `getFrames`. +La forma más rápida es pegar esto en Claude Code: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +El skill instala OpenScreen si falta, una vez que aceptes, y agrega su servidor MCP. Luego te pide que abras una nueva sesión y digas *continue the OpenScreen demo*: un agente solo obtiene herramientas nuevas en una nueva sesión. Para configurarlo a mano en cambio: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md index 99ca7526e9..969224d10f 100644 --- a/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/fr/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ Les outils sont ceux qu'utilise l'agent intégré, et ils agissent sur le projet Le serveur ci-dessus modifie des projets. Pour qu'un agent fasse une vidéo entière tout seul, de l'enregistrement à l'export, ajoutez plutôt OpenScreen à l'agent comme serveur stdio : l'agent lance l'exécutable même de l'application avec `mcp`. Il dispose des mêmes outils d'édition, plus `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo` et `getFrames`. +Le plus rapide est de coller ceci dans Claude Code : + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +La skill installe OpenScreen s'il manque, une fois que vous avez accepté, et ajoute son serveur MCP. Elle vous demande ensuite d'ouvrir une nouvelle session et de dire *continue the OpenScreen demo* : un agent n'obtient de nouveaux outils que dans une nouvelle session. Pour tout configurer à la main à la place : + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md index 6a4c3089ba..c0008346af 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ Claude Code や Codex などの AI コーディングエージェントをすで 上のサーバーはプロジェクトを編集するものです。録画からエクスポートまで、エージェントに動画全体を自力で作らせるには、代わりに OpenScreen を stdio サーバーとしてエージェントに追加します。エージェントは、アプリ自身の実行ファイルを `mcp` 付きで起動します。エージェントは同じ編集ツールに加えて、`listSources`、`startRecording`、`stopRecording`、`setPointerTrack`、`exportVideo`、`getFrames` を使えます。 +いちばん手早いのは、次の内容を Claude Code に貼り付けることです。 + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +このスキルは、OpenScreen がなければ、同意を得たうえでインストールし、その MCP サーバーを追加します。続いて、新しいセッションを開いて *continue the OpenScreen demo* と伝えるよう求めます。エージェントが新しいツールを得られるのは、新しいセッションの中だけです。代わりに手動で設定するには、次のようにします。 + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md index f5c831fc22..f43cfe39df 100644 --- a/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/pt-BR/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ As ferramentas são as que o agente integrado usa, e elas agem sobre o projeto a O servidor acima edita projetos. Para que um agente faça um vídeo inteiro sozinho, da gravação à exportação, adicione, em vez disso, o OpenScreen ao agente como servidor stdio: o agente inicia o próprio executável do app com `mcp`. Ele recebe as mesmas ferramentas de edição, mais `listSources`, `startRecording`, `stopRecording`, `setPointerTrack`, `exportVideo` e `getFrames`. +O jeito mais rápido é colar isto no Claude Code: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +A skill instala o OpenScreen se ele estiver faltando, depois que você concordar, e adiciona o servidor MCP dele. Em seguida, ela pede que você abra uma nova sessão e diga *continue the OpenScreen demo*: um agente só recebe ferramentas novas em uma nova sessão. Para configurar à mão, em vez disso: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md index f727bc791a..1cd4f51b61 100644 --- a/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ ChatGPT 和 GitHub Copilot 登录选项已**在 1.8.0 中移除**。它们的工 上面的服务器用于编辑项目。若要让 AI 代理从录制到导出独立完成一整段视频,请改为把 OpenScreen 作为 stdio 服务器添加到 AI 代理中:AI 代理会用 `mcp` 启动应用自身的可执行文件。它能使用同样的编辑工具,另外还有 `listSources`、`startRecording`、`stopRecording`、`setPointerTrack`、`exportVideo` 和 `getFrames`。 +最快的方式是把下面这段内容粘贴到 Claude Code 中: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +如果缺少 OpenScreen,该技能会在你同意后安装它,并添加它的 MCP 服务器。随后它会请你打开一个新会话,并说出 *continue the OpenScreen demo*:AI 代理只有在新会话中才能获得新工具。若要改为手动设置: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp diff --git a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md index 96f446691d..df89122252 100644 --- a/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md +++ b/website/i18n/zh-TW/docusaurus-plugin-content-docs/current/ai-editing.md @@ -73,6 +73,14 @@ ChatGPT 與 GitHub Copilot 的登入選項已**在 1.8.0 中移除**。它們的 上述伺服器用於剪輯專案。若要讓代理從錄影到匯出自行製作一整支影片,請改為將 OpenScreen 以 stdio 伺服器的形式加入代理:代理會以 `mcp` 啟動應用程式本身的執行檔。它能使用相同的剪輯工具,另外還有 `listSources`、`startRecording`、`stopRecording`、`setPointerTrack`、`exportVideo` 與 `getFrames`。 +最快的方式是將下面這段內容貼到 Claude Code 中: + +```text +Install the OpenScreen demo skill with `npx skills add getopenscreen/openscreen --skill openscreen-demo -a claude-code`, then follow it to make a demo video of this feature. +``` + +如果缺少 OpenScreen,該技能會在你同意後安裝它,並加入它的 MCP 伺服器。接著它會請你開啟一個新的工作階段,並說出 *continue the OpenScreen demo*:代理只有在新的工作階段中才能取得新工具。若要改為手動設定: + ```bash claude mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp codex mcp add openscreen -- "/Applications/Openscreen.app/Contents/MacOS/Openscreen" mcp From ee518cdd00ce3661b577f02a6c42fdf593f46aba Mon Sep 17 00:00:00 2001 From: EtienneLescot Date: Mon, 12 Oct 2026 11:35:25 +0200 Subject: [PATCH 2/2] docs(skill): the macOS Accessibility permission that click zooms need From review: without it macOS records no pointer clicks, so a real-mouse take gets no zoom on them. --- skills/openscreen-demo/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/openscreen-demo/SKILL.md b/skills/openscreen-demo/SKILL.md index 53767a0724..3c9ece795c 100644 --- a/skills/openscreen-demo/SKILL.md +++ b/skills/openscreen-demo/SKILL.md @@ -37,7 +37,7 @@ Run `"" help`: it must list `mcp`. If the app is missing, or too old - **Cursor and others:** a stdio server with the executable as `command` and `["mcp"]` as `args`. **Permissions.** -- **macOS:** the app that runs the agent needs the Screen Recording permission, in System Settings → Privacy & Security. +- **macOS:** the app that runs the agent needs, in System Settings → Privacy & Security, the Screen Recording permission to record at all, and the Accessibility permission for OpenScreen to record the pointer's clicks and shapes. Without Accessibility a take driven with the real mouse gets no zoom on its clicks: grant it, or hand the clicks over with `setPointerTrack` as for a scripted take. - **Linux:** the desktop's picker opens on every recording, and the user chooses the window. **Hand over to the next session.** Write the user's request, and anything already decided, to `openscreen-demo-plan.md` in the working directory. Then ask the user to start a new session and say *continue the OpenScreen demo*. In that session, read the file and carry on from step 2.