Agent Screenplay

At a glance

Agent Screenplay is an MIT-licensed tool that turns a short JSON scenario into an edited screen recording of a website or desktop app. Your coding agent (Claude Code, Codex, Cursor or another MCP client) explores the target and writes the scenario. Screenplay then plays it, films it, and adds zooms, a drawn cursor, captions and optional voice-over, producing an MP4 and a storyboard image. It contains no AI and needs no model key.

Good fit

Developers and product teams who already work with a coding agent and want repeatable product demos, feature walkthroughs or release videos. Because each video comes from a scenario file, you can change the style, captions or voice and re-render without filming again. That suits demos that must be redone whenever the interface changes.

Consider something else when

Skip it if you want to capture yourself working by hand, since Screenplay films scripted steps rather than live sessions. It also fits poorly when the target site asks a person to pass a bot check on every visit, which cannot be filmed automatically, or when you need desktop recording on Wayland Linux or inside a headless container.

Start here

With Node 20 or later, run npx agent-screenplay init. It downloads Chromium, registers the MCP server with Claude Code, Codex or Cursor, and installs a scenario guide. Restart your agent, then in Claude Code type /screenplay followed by a request such as a 30-second walkthrough of a URL. Success is an MP4 plus a storyboard PNG. Start on a demo account or staging site, because check and record perform every step for real, including clicks that send messages.

Cost and requirements

The npm package is free under the MIT licence and bundles ffmpeg and its drawing library, so Node 20 or later is the main requirement. Voice-over is optional and needs your own Cartesia or ElevenLabs API key, or audio files you supply. Desktop recording needs Screen Recording and Accessibility permission on macOS, nothing extra on Windows, and an X11 session with the AT-SPI accessibility bus on Linux.

Limits to know

Desktop recordings need a real screen and cannot run in a headless container, and Wayland is not supported. Whole-screen mode films everything visible, including desktop icons and notifications. Saved sign-in sessions are written to .screenplay/auth.json, which should be kept out of git. Sites that demand a human check on every visit cannot be filmed automatically. The bundled ffmpeg is GPL-licensed, unlike the MIT-licensed package itself.

Still unclear

• Does Screenplay send any usage data or recordings anywhere other than the voice provider you configure?
• How well do the automatic zooms and drawn cursor cope with fast-changing or heavily animated interfaces?