Guide · Agent skill

How to use the Browser CDP Control agent skill (browser-cdp)

Updated 2026-11-02 · written with AI from the project's own documentation and checked against our catalogue data

The browser-cdp skill lets an AI agent control a Chrome browser on your computer through the Chrome DevTools Protocol (CDP), so it can work with sites you are already logged into. This guide is for developers and data collectors who are comfortable reviewing shell commands. By the end you will know how to install the skill, trigger it with plain requests, run its setup script safely, and understand what it can read from your browser.

Browser CDP Controlzenstory-ai/oh-story-claudecode · MIT Download the skill

Quick start

1Check the prerequisites. Confirm Node.js 20+ is installed, Google Chrome has been used at least once on this machine, and the agent-browser CLI is available.
2Install the skill folder. Download the ZIP from the page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
3Run the detect-only check. Run the setup script with --detect-only on port 9222 to see whether CDP is ready and whether Chrome is running.
4Confirm before closing Chrome. If Chrome is running and must be restarted, run with --dry-run, review the number of processes, and agree before any rerun with --yes.
5Connect and open a page. Use agent-browser with --cdp 9222 to open a URL and wait for it to load.
6Read or interact with the page. Use eval for text or values, and snapshot -i with click or type for interaction.

What the browser-cdp skill makes the agent do

A skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. This one covers controlling Chrome via CDP to reuse existing login sessions. Its documented operations include launching Chrome in debug mode, opening URLs, waiting for page load, evaluating JavaScript, taking snapshots of interactive elements, clicking and typing, and extracting auth tokens such as a localStorage item or a JavaScript-readable cookie.

Open a URL and wait for the page to load
Extract page text
Run JavaScript on the page with eval
Take a snapshot of interactive elements and click or type into them
Read a token from localStorage or document.cookie, where the site allows it

Install the browser-cdp skill

Download the ZIP for the skill from our page and unzip it. For a personal install, put the folder in ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

The skill also needs its runtime tools. The source says you need Node.js 20+, Google Chrome installed and used at least once on the machine, and the agent-browser CLI, installed with the command below.

Node.js 20 or newer
Google Chrome installed and signed in to the sites you need at least once
agent-browser CLI

npm install -g agent-browser

Run the setup safely: detect first, then start

The SKILL.md asks the agent to run a read-only detection step before anything changes. Replace {SKILL_DIR} with the skill's folder path. The detect output reports whether CDP is already ready, whether Chrome is running, and how many Chrome processes exist.

If the status is ready, the agent connects directly with agent-browser and does not run setup. If Chrome is not running and setup is needed, the agent starts it with --yes. If Chrome is running, the setup can close those processes, so the skill requires a dry run first, a clear question to you about how many processes will close and that unsaved tabs may be lost, and only then a rerun with --yes.

--detect-only: checks state and changes nothing
--dry-run: prints the steps without running them
--yes: skips the prompt after you have agreed
--reset: empties ~/chrome-debug-profile before starting (use when logins have expired)
--profile <name>: picks the source profile, default Default; passing it rebuilds the debug profile
Exit codes: 0 success, 1 general error, 2 user declined, 3 consent needed but --yes missing

node {SKILL_DIR}/scripts/setup-cdp-chrome.js 9222 --detect-only

Open pages and read or act on them

Once Chrome is ready on port 9222, the agent uses agent-browser with --cdp 9222. Opening a page and waiting is the basic pattern. To read text, it evaluates a short JavaScript expression. For complex scripts with quotes, dollar signs or backticks, the skill recommends passing code as base64 or through standard input to avoid shell escaping errors.

For interaction, the agent takes a snapshot of interactive elements to get references, then clicks or types using a CSS selector or an element reference such as @e1.

agent-browser --cdp 9222 open "<URL>"
agent-browser --cdp 9222 wait 3000
agent-browser --cdp 9222 eval 'document.body.innerText.substring(0, 8000)'
agent-browser --cdp 9222 snapshot -i
agent-browser --cdp 9222 click "<CSS or @e1>"

Stop the debug browser and recover from common problems

Close the debug Chrome window to stop it. If the window stops responding, the skill says to find the debug instance's process ID by matching the chrome-debug-profile path, then end only that PID. It explicitly forbids bulk-killing processes by the Chrome executable name during manual cleanup.

If logins expire, the source recommends rerunning setup with --reset after the same dry-run and consent steps. If the port is taken, you can switch to another port, such as 9333, and use it in every later command.

NEEDS_CONSENT with exit code 3: run the dry run, agree, then add --yes
CDP port not listening: run --detect-only, then change the port if it is in use
Page redirects to a login page: take a snapshot and click the login button
eval returns null: check the localStorage key name, or use eval -b or --stdin for quoted JavaScript
Chrome does not start within 30 seconds: check for a port conflict or a damaged ~/chrome-debug-profile/ folder

pgrep -af chrome-debug-profile

What people use it for

Fetch a page that sits behind your existing login, such as a dashboard you already use
Collect text from several pages of an authenticated site, one page at a time with timeouts
Check whether a logged-in page shows the expected value by evaluating a short JavaScript expression
Read a token stored in localStorage for a site you are authorized to use, after confirming where the site stores it

Frequently asked questions

Is the browser-cdp skill free?

The skill is published under the MIT licence, as stated on this page. Its runtime needs also include Node.js and Google Chrome, and the agent-browser CLI, which is installed with npm install -g agent-browser.

What do I need to use the browser-cdp skill?

You need Node.js 20 or newer, Google Chrome installed and used at least once on the machine, and the agent-browser CLI. The skill runs scripts and uses the network, so review its files before installing.

How do I install the browser-cdp skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Does the setup script close my Chrome windows?

It can. If Chrome is running, the setup stops all Chrome processes it needs, so the skill requires a dry run first and your consent before a rerun with --yes. Unsaved tabs or drafts may be lost, so save your work first.

Why does the skill say eval returns null?

The source notes that eval returning null usually means the localStorage key name is wrong. Check the key, and use eval -b or --stdin when your JavaScript contains quotes, dollar signs or backticks.

Is browser-cdp safe to use on a shared computer?

The skill itself warns against it. A copied profile and an open debug port can expose your logged-in sessions to other local processes, so use it only on a machine you control.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use browser-cdp if you are a developer or data collector who automates sites you already log into, and you are comfortable reviewing shell commands and approving process shutdowns. Pick a different approach if you do not want an agent reading tokens or cookies from your browser, if you cannot risk interrupting unsaved work, or if the machine is shared.

Download the skill