🎬 DevDemo

The Official Terminal Screen Recorder for AI Coding Agents. Let your agent build the code and record the demo video.

DevDemo is a powerful, headless, zero-dependency screen recording CLI engineered explicitly for Autonomous AI Agents and Developer Workflows.

If you use Cursor, Windsurf, Copilot, Claude Code, CodeX, OpenCode, or Antigravity, you know they can write phenomenal code. But how do they prove it works? How do they show you the UI they just built?

With DevDemo, the coding agent itself can autonomously record a 60-second video demo of the feature it just built. No more guessing if the Playwright test actually rendered correctly, or asking the agent to "describe what the UI looks like." Tell the agent to build the feature, and command it to use devdemo to record a video of the final result.

🚀 Installation

Ensure you have FFmpeg and Node.js >= 18 installed.

# Install globally via npm
npm install -g @coderbunch/devdemo

🤖 1. Autonomous Agent Mode

DevDemo is specifically built for machine interaction. Agents don't need to read complicated -help menus to record videos.

devdemo task (Natural Language Parser)

Agents can generate optimal recording JSON configs simply by passing a natural English description.

devdemo task "record my display and my microphone at 60fps"
# Instantly generates a devdemo.config.json tailored to your OS

devdemo init (Workspace Scaffolding)

Instantly scaffolds a .devdemo/templates/ directory containing standard AI workspace presets like bug-report.json, terminal-demo.json, and agent-workflow.json.

devdemo export --json (Machine-Readable Output)

Every CLI interaction can be muted and forced into a strict JSON payload so LLM agents can perfectly parse the absolute file paths and statuses gracefully.

devdemo export . -o tutorial.mp4 --json
# Output: { "status": "success", "output_path": "/absolute/path/tutorial.mp4" }

🧠 Pre-Built Agent Instructions

Want your own AI coding assistant to use DevDemo automatically? Copy and paste our highly-optimized Agent System Instructions directly into your .cursorrules, .windsurfrules, or Claude system prompt!

# [System Instructions: Autonomous Video Recording]

You are equipped with `@coderbunch/devdemo`, a headless CLI tool that allows you to record your screen, extract video frames into images, and automatically generate mp4 video tutorials of the features you build. 

Whenever the user asks you to "record a demo", "show me what you built", or "run a visual test", you MUST use `devdemo` autonomously.

## 🛠️ DevDemo Core Commands:

1. RECORDING: 
   - Start recording the screen in the background:
     `npx devdemo record --screen --json`
   - Wait asynchronously or run your tests.
   - Stop recording:
     `npx devdemo stop --json`

2. VISION EXTRACTION:
   - To find the exact visual location of a UI element after recording, extract frames into an image sequence:
     `npx devdemo extract frames . --fps 1 -o ./devdemo-frames --json`
   - Use your Vision API capabilities to read those `.png` images and locate timestamps or UI elements.

3. ANNOTATION INJECTION:
   - Based on the timestamp or coordinate data you gathered from the frames, you can inject visual burn-in events before exporting the video:
     `npx devdemo event --click 150,300`

4. FINAL EXPORT:
   - When the workflow is complete, algebraically composite the raw captures into a beautiful 16:9 mp4:
     `npx devdemo export . -o final_demo.mp4 --layout pip --json`

5. UPLOAD / PUBLISHING:
   - Upload autonomously to a free temporary host (like transfer.sh) and return the URL:
     `curl --upload-file ./final_demo.mp4 https://transfer.sh/demo.mp4`

## 🚨 Critical Rules for the Agent:
- You must always append `--json` to `devdemo` commands.
- Never wait continuously on `devdemo record`. It runs in the background. Move on to the next command.

🎥 2. Recording Capabilities

DevDemo operates natively on both the raw X11 display server and the highly secure Wayland XDG Desktop Portals without relying on massive unwieldy Electron dependencies.

Standard Capture

Record your whole screen, or isolate specific tracks:

devdemo record --screen
devdemo record --screen --mic --camera --fps 60

Targeted Region Capture

Only care about a specific coordinate of your screen? Pass the exact X, Y, Width, Height:

devdemo record --region 100,100,800,600

Headless Browser Recording

Running in a CI/CD pipeline or a headless server without X11 or Wayland? No problem. DevDemo can use Playwright to spin up a fully headless browser and record it seamlessly:

# Starts Chromium, navigates to the URL, records for 10s, and auto-stops
devdemo record --url "http://localhost:3000" --duration 10

Graceful Session Control

Pause and resume live recordings smoothly from another terminal:

devdemo pause
devdemo resume
devdemo stop

🏎️ 3. The "One-Command" Agent Workflow

Because AI coding agents work best when given high-level directives, DevDemo features a flawless one-command pipeline that starts your dev server, waits for the URL to respond, records a session, exports an MP4, and cleans up the background server:

# Start your Next.js/Vite app, record it, and export
devdemo demo --cmd "npm run dev" --url "http://localhost:3000" --duration 5 -o my_tutorial.mp4

Instant URL Sharing

AI agents can't simply send file attachments directly into chat windows easily. Once the demo is recorded, you can ask your agent to share it:

devdemo share ./my_tutorial.mp4

Uploads the media to a frictionless transient file host (uguu.se) and immediately returns a public URL (https://h.uguu.se/ABCD.mp4) that the agent can link back to the user!

🎯 4. Smart Polish Events

Don't just record a video. Instruct DevDemo to burn highlight overlays into the video dynamically.

While a recording session is active (e.g. while an Agent is running a browser test), you can inject real-time timeline events. During export, the FFmpeg engine will losslessly burn these highlights into the final video!

# Inject an animated red pulse exactly where the agent clicked
devdemo event --click 150,200

# Burn a fading text annotation over the video
devdemo event --annotate "Deploying to production..." --duration 3

# (Coming soon) Notify the exporter to zoom the camera onto these coordinates
devdemo event --zoom 500,500,400,300

🎞️ 5. Advanced Composition Layouts

Did you capture your --screen, --mic, and --camera? Don't leave them as raw individual files. DevDemo acts as a programmatic composition engine!

# Export as Picture-in-Picture
# Rounds your raw webcam into a perfect circular crop and places it in the corner of a padded 16:9 canvas!
devdemo export . -o final.mp4 --layout pip

# Export as Side-by-Side
# Places your screen on the left, and scales your webcam matrix to the right pane natively
devdemo export . -o final.mp4 --layout split

DevDemo's compose engine automatically detects if a mic.wav track is present in your session directory and injects intelligent Audio Ducking so your voice sits perfectly over the system background noise.

👁️ 6. Vision Extraction Utilities

If your autonomous agent recorded a generic workflow and suddenly wants to edit out a typo or find the exact X,Y coordinates of a UI button, how can it "see" the video?

DevDemo features headless frame extraction utilities designed specifically for Multi-Modal Vision LLMs (like GPT-4o or Claude 3.5 Sonnet).

# Dump the entire video into a grid of PNGs (1 frame per second)
# Agents can pass these frames to a Vision model to find the exact timestamp of an event!
devdemo extract frames tutorial.mp4 --fps 1 -o ./vision_grid --json

# Extract a single high-quality frame natively at a specific timestamp
# Agents can feed this to a Vision model to get exact bounding box coordinates!
devdemo extract frame tutorial.mp4 --time 00:00:15.500 -o target.png --json

✂️ 7. Lossless Editing Utilities

Finished recording? You don't need to open Premiere Pro. DevDemo features instant, lossless terminal editing utilities that utilize FFmpeg stream-copies to process edits in milliseconds without re-encoding quality loss.

Slicing / Trimming

devdemo edit slice raw_capture.mp4 --start 00:00:15 --end 00:00:45

Merging / Concatenation

devdemo edit merge intro.mp4 raw_capture.mp4 outro.mp4 -o final_release.mp4

🧩 8. VS Code IDE Companion

DevDemo ships alongside a native IDE Extension: @coderbunch/devdemo-vscode.

Inside Visual Studio Code, press Ctrl+Shift+P -> DevDemo: Record Screen. A beautiful 🔴 Recording UI will lock into your VS Code Status bar, enabling seamless single-click record toggling and command palette exports.

🤝 Contributing & License

We welcome pull requests!

git clone https://github.com/coderbunch/devdemo.git
npm install
npm run build

Released under the MIT License.