> ## Documentation Index
> Fetch the complete documentation index at: https://jam.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  `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.
</Info>

## 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:

```bash theme={"theme":"css-variables"}
jam skills install
```

Then ask in English:

```text theme={"theme":"css-variables"}
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.

```text theme={"theme":"css-variables"}
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](https://github.com/vercel-labs/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.

```bash theme={"theme":"css-variables"}
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](https://github.com/ChromeDevTools/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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Point the MCP at the proxy">
    ```bash theme={"theme":"css-variables"}
    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.
  </Step>
</Steps>

## 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:

```bash theme={"theme":"css-variables"}
proxy=$(jam record start --cdp 9222 --json | jq -r .cdpProxy)
JAM_CDP_PROXY="$proxy" node checkout.spec.js
jam record stop --json
```

```js theme={"theme":"css-variables"}
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](/docs/cli#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.