Skip to main content
When an AI agent drives a browser, the Jam should carry what the agent saw: the console errors, the failed requests, and every click and keystroke, lined up with the video. jam record gets these from the browser over the Chrome DevTools Protocol, the same protocol agents use to drive Chrome. You point one flag at the agent’s browser, and the Console, Network, and user-action panels fill themselves. This page shows how to connect the agents and tools we have tried. The video and the panels both come from the browser itself, so the browser can be headless and nothing new runs on the page under test.
Recording a browser over --cdp works on macOS, Linux, and Windows. It needs a Chromium-based browser, which covers Chrome, Edge, and the Chromium that agent tools launch.

​
What the video shows

With one --cdp, the video comes from Chrome by default. Chrome sends a picture of the page each time it changes, and the CLI turns those pictures into a 30 fps video on the same clock as the console and network rows. Pick screen capture instead with --video-source screen. Repeating --cdp records several browsers in one screen recording, with their events combined. Naming a window or display with --window-id, --app, --bundle-id, --pid, or --display also switches to screen. A screencast needs ffmpeg, and jam record start says how to install it when it is missing.

​
The two ways to connect

An agent’s browser reaches a recording one of two ways. Both need a browser the CLI can reach on a debug port.
  • Tap. jam record start --cdp <port> attaches to the Chrome the agent drives. The Console and Network panels fill from every open tab.
  • Proxy. With --cdp, jam record start also prints a cdpProxy address. Point the agent at that address instead of at Chrome, and its clicks and keystrokes become user actions in the Jam. This is how you record actions without changing the agent.

​
Ask your agent to do it

With the skills installed (see the Jam CLI quickstart), ask in English:
The agent launches its own Chrome, starts the recording, drives through the proxy, and returns the link. Asking for proof or a recorded Jam triggers the same skill.

​
If your agent cannot load skills

Paste the procedure instead, with your own claim in the title.
Step 4 lets the recorder see the agent’s own commands: each click is matched to the element under it before the page changes, and a page the agent opened is told apart from one the page went to by itself. An agent that skips it still gets the video, the browser’s console and network, and the clicks and typing it makes on the page.

​
agent-browser

agent-browser is a command-line tool that drives Chrome, headless by default. Let it launch its browser, record that browser, then drive through the proxy so the clicks land.
Drive with a second session. If the session that launched Chrome connects elsewhere, agent-browser closes that Chrome and the recording loses its browser.

​
chrome-devtools-mcp

chrome-devtools-mcp is an MCP server that connects to a running Chrome. Because it takes a browser URL, it takes the proxy’s URL.
1

Start recording with the tap

Start jam record start --cdp <port> against the Chrome the MCP will drive, and read the cdpProxy address from the receipt.
2

Point the MCP at the proxy

The MCP’s navigate, click, and type calls pass the recorder, so they are recorded as user actions. Stop with jam record stop <session> when the run is done.

​
Playwright and Puppeteer scripts

A script that connects to a running Chrome drives it over the same protocol, so it takes the proxy’s address in place of the browser’s. Wrap the script in jam record run --cdp <port>, and the CLI passes the proxy address to it in JAM_CDP_PROXY. Playwright’s chromium.connectOverCDP and Puppeteer’s connect({ browserURL }) both take it. Headless or not, the script records the same way. The full example, and how to upload a failed Playwright run after the fact, is in Record end-to-end tests. Playwright’s route.fetch() and route.fulfill() work through the proxy. Register routes before navigation or prefetch. A later click may use the app’s cache without sending a new request.

​
Computer-use agents

An agent that moves the real mouse and reads the screen, rather than speaking the DevTools protocol, sends no commands for the recorder to see. If its browser was launched with a debug port, tap it anyway with jam record start --cdp <port> --video-source screen. The Console and Network panels fill from the browser’s own events, the screen video shows the cursor the agent moves, and its clicks and typing are recorded from the page, with the element each one hit. While a driver is connected to the cdpProxy address, actions come from that driver’s commands instead, so no action is recorded twice.

​
agent-desktop

agent-desktop drives native apps through the operating system’s accessibility tree. It sees Chrome as one more app, so it clicks the page through the accessibility API, not the DevTools protocol. Launch Chrome with a debug port, tap it with --cdp, and let agent-desktop drive the window.
The Console and Network panels fill from the browser, and the video is the page screencast. The user-action rows stay empty, because agent-desktop sends no command through the proxy. To keep the steps on the timeline, have the agent write one line per command to a marks file, {"at": <unix ms>, "label": "click Place order"}, and pass it to jam record stop --marks. Each mark becomes a comment at its moment in the video. For a task that stays inside the page, agent-browser through the proxy records every click and keystroke as a user action.

​
Browsers the CLI cannot reach

An agent that runs as a Chrome extension drives your normal browser, and an app with a built-in browser pane, such as the Codex desktop app, keeps it to itself. Neither exposes a debug port, so neither path reaches them. Record the window with jam record start --app <name> for the video, and read the agent’s own logs for the rest.

​
Any other tool

The pattern is the same whatever drives the browser. Get a DevTools address for the browser, start the recording with --cdp on that address, and give the printed cdpProxy address to the tool wherever it takes a browser URL or a DevTools endpoint. The video, the console, and the network come from the browser either way. User actions come from any tool that drives over the protocol.

​
What the Jam contains

The Jam’s panels mirror the browser. Console lines, uncaught exceptions, and network requests with their headers and status come from the browser’s own events. Bodies come from fetch and XHR requests, as text under 256 KB. A document, script, or image body reads as unavailable, and secret-bearing headers and parameters are redacted. Clicks and typed values come from the agent’s commands through the proxy, or from the page itself when no driver is connected to the proxy, with the element each one hit. Typed text on a password, one-time-code, card, or sensitively named field is masked.

​
Record several browsers in one Jam

Launch two Chromes with separate profiles and remote debugging ports 9222 and 9223. Repeat --cdp to combine their Console and Network events in one Jam:
Multiple browsers use screen video by default: select a display that shows both browsers, or a window. Without a selector, Jam records the primary display. --video-source screencast films one page and cannot record multiple browsers. The wrapped script receives $JAM_CDP_PROXY for the first browser and $JAM_CDP_PROXIES for all proxies, space-separated in --cdp order. Connect each driver to its corresponding proxy to record clicks and typing. The start receipt lists each endpoint and proxy in browsers, in the same order; the singular cdpEndpoint and cdpProxy still name the first browser. If any browser quits, the recording is discarded with exit code 12 and names that endpoint.