Record an agent's browser

Record an AI agent’s browser into a Jam, headless or not, with its console, network, and clicks. Connect agent-browser, chrome-devtools-mcp, or a Playwright script to jam record.

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 already 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.

jam record runs on macOS and Linux. Recording a browser this way needs a Chromium-based browser, which covers Chrome, Edge, and the Chromium that agent tools launch.

What the video shows

With --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.

--video-source	What the video shows	Use it when
screencast (default with --cdp)	The page inside the tab. No address bar, tabs, cursor, or Chrome dialogs. It follows the tab Chrome shows.	Most recordings. It works for a headless browser, needs no Screen Recording permission, draws no outline, and never shows other windows on your screen.
screen	The browser window or the whole display, as it looks on screen.	You need the browser’s own UI, the cursor, or a native dialog in the video. It needs a visible window.

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 names the install command 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 a Chrome the agent already 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

Install the skills once, and the whole procedure below is already where your agent reads it:

jam skills install

Then ask in English:

Record yourself reproducing the checkout bug in the browser, then send me the Jam link.

The agent launches its own Chrome, starts the recording, drives through the proxy, and hands back the link. Ask for proof, evidence, or show me and it reaches for the same skill.

If your agent cannot load skills

Paste the procedure instead, with your own claim in the title.

Record what you do in the browser as a Jam, and give me the link at the end.

1. Check the CLI is signed in with `jam auth status`, and run `jam auth login` if it is not.
2. Get a DevTools address for the Chrome you drive. If your tool launched it, ask the tool
   (agent-browser: `agent-browser get cdp-url`). Otherwise launch Chrome with
   --remote-debugging-port=9222 --user-data-dir=/tmp/jam-chrome and use 9222.
3. Start the recording on that address, and keep `cdpProxy` from the receipt:
   jam record start --cdp <address> --title "<what you are showing me>" --json
4. Point your browser tool at the `cdpProxy` address instead of at Chrome, then do the work.
5. Finish with `jam record stop --json` and return the `url` from the receipt.

Step 4 is what puts the clicks in the Jam. An agent that skips it still gets the video and the browser’s console and network, but no user actions.

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.

agent-browser open about:blank                                                   # session A launches headless Chrome
agent-browser get cdp-url                                                        # → ws://127.0.0.1:<port>/devtools/browser/…
jam record start --cdp <cdp-url> --title "Checkout completes" --json             # → { session, cdpProxy }
agent-browser --session jam --cdp <cdpProxy> open https://example.com/checkout   # a second session drives through the proxy
jam record stop --json

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 a Model Context Protocol 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

   chrome-devtools-mcp --browserUrl http://127.0.0.1:<cdpProxy port>
   

   The MCP’s navigate, click, and type calls pass the recorder, so they land as user actions. Stop with jam record stop 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.

Read the address from the start receipt and pass it to the script:

proxy=$(jam record start --cdp 9222 --json | jq -r .cdpProxy)
JAM_CDP_PROXY="$proxy" node checkout.spec.js
jam record stop --json

const browser = await chromium.connectOverCDP(process.env.JAM_CDP_PROXY);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com/checkout");
await page.getByRole("button", { name: "Pay now" }).click();

Headless or not, the script records the same way. Puppeteer’s connect({ browserURL }) takes the same address. For a Playwright run you keep after the fact rather than recording live, jam create jam reads the video and trace directly. See Turn a Playwright failure into a watchable Jam.

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 still fill from the browser’s own events, and the screen video shows the cursor the agent moves. Only the user-action rows are missing, because there is no command to record.

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 hand 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 lands in the Jam

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 own commands through the proxy, with the element each one hit. Typed text on a password, one-time-code, card, or sensitively named field is masked.