record-screen

name	record-screen
description	Record a Chrome browser tab to video via CLI. Use when the user wants to capture a screen recording of a browser tab. Supports list, start, stop, caption, and status subcommands. No debug mode required — uses a Chrome extension.
argument-hint	[list | start --tab <n> --out <file> | caption <text> | stop | status]
allowed-tools	Bash
disable-model-invocation	false

Screen Recording Tool

Records Chrome browser tabs to MP4/WebM video using a Chrome extension + bridge server. No --remote-debugging-port flag needed — works with normal Chrome.

First-time setup

1. Install Node dependencies:

   cd .claude/skills/record-screen/scripts && npm install
   

2. Load the Chrome extension:

   • Open chrome://extensions in Chrome
   • Enable Developer mode (toggle in top-right)
   • Click Load unpacked
   • Select the .claude/skills/record-screen/extension folder

That's it. The bridge server auto-starts when you run any command.

Commands

Run the recording script with:

node .claude/skills/record-screen/scripts/record.js $ARGUMENTS

Subcommands

Command	Description
list	List available Chrome tabs with their index numbers
start --tab <n> [--out file.mp4]	Start recording tab number n
caption <text>	Add a timestamped caption at the current point in the video
stop	Stop the active recording and save the video + captions file
status	Check if a recording is active and extension is connected

Start options

Flag	Default	Description
--tab <n>	(required)	Tab number from list or Chrome tab ID
--out <file>	recording.mp4	Output file path (.mp4 or .webm)

Behavior

If no arguments are provided or just list: Run the list command to show available tabs, then ask the user which tab to record and what to name the output file.

For start: The recording runs server-side — the command returns immediately. Remind the user to use /record-screen stop when finished.

For caption: Logs a caption at the current video timestamp. The timestamp is recorded server-side and converted to video time when the recording stops, so it aligns precisely with the encoded video.

For stop: Wait for encoding to complete (may take a few seconds for MP4 transcoding), then report the output file path, duration, file size, and captions file path.

For status: Shows whether a recording is active and whether the Chrome extension is connected to the bridge server.

Captions

You MUST log captions during recording. For every visible action you take on the page, run the caption command in parallel (in the same message) as the browser action. This creates a .captions.json file alongside the video that maps your actions to video timestamps.

Caption rules:

• Call the caption in the same tool-call message as the browser action (parallel execution), NOT sequentially after it
• Use curl for captions (NOT node record.js caption) — curl starts instantly vs ~1s for Node.js, giving much better timing accuracy
• Only log captions for visible actions (scroll, click, type, navigate). Do NOT log captions for waits, screenshots, or other non-visible actions
• Describe what you are doing, e.g. "Scrolling down", "Clicking the search button", "Typing 'hello' into the search box"
• Keep captions short and factual

Caption command (use this exact format):

curl -s -X POST http://localhost:9234/api/caption -H "Content-Type: application/json" -d "{\"text\":\"YOUR CAPTION HERE\"}"

Example — call BOTH tools in the same message:

[Tool 1 - Browser action]:  scroll down on the page
[Tool 2 - Bash]:            curl -s -X POST http://localhost:9234/api/caption -H "Content-Type: application/json" -d "{\"text\":\"Scrolling down the page\"}"

Both execute simultaneously, so the caption timestamp matches when the action happens in the video.

Example workflow:

node record.js start --tab 1 --out demo.mp4
# For each action, call the browser tool AND curl caption in parallel:
#   browser: navigate to Wikipedia  +  bash: curl caption "Navigating to Wikipedia"
#   browser: type in search box     +  bash: curl caption "Searching for Claude AI"
#   browser: scroll down            +  bash: curl caption "Scrolling down"
#   browser: click link             +  bash: curl caption "Clicking the Anthropic link"
node record.js stop

The captions file is saved as <video-name>.captions.json in the same directory as the video. Format:

{
  "videoFile": "demo.mp4",
  "videoDuration": 15.2,
  "fps": 5,
  "totalFrames": 76,
  "captions": [
    { "videoTime": 1.2, "text": "Navigated to Wikipedia main page" },
    { "videoTime": 4.6, "text": "Searched for Claude AI" },
    { "videoTime": 8.0, "text": "Scrolled down the page" },
    { "videoTime": 11.4, "text": "Clicked on the Anthropic link" }
  ]
}

Important notes

• The recorded tab must stay visible and active in its Chrome window during recording. The extension uses captureVisibleTab which captures whatever is currently shown.
• Frames are captured at ~5 FPS as JPEG screenshots, then encoded to video via FFmpeg on stop.

Output formats

• .mp4 — H.264 encoded via FFmpeg (recommended, most compatible)
• .webm — VP9 encoded via FFmpeg

Architecture

The tool has three parts:

1. Chrome extension — uses chrome.tabs.captureVisibleTab() to take screenshots at 5 FPS and streams them to the bridge server
2. Bridge server — Node.js HTTP+WebSocket server on port 9234 that connects CLI to extension, saves frames to disk, and encodes video with FFmpeg
3. CLI — sends HTTP commands to the bridge server

The bridge server auto-starts in the background when you run list, start, stop, or status. The Chrome extension auto-connects to it.

Output labels

The script outputs machine-readable labels:

• RECORDING_STARTED / RECORDING_STOPPED / RECORDING_ACTIVE / NO_ACTIVE_RECORDING
• CAPTION_ADDED @ <time> — caption was logged
• TAB: / FILE: / DURATION: / SIZE: / EXTENSION: / CAPTIONS: — metadata