chrome-cdp-skill

Interact with a local Chrome-family browser session over CDP when the user explicitly asks to inspect, debug, or interact with a page they already have open.

Security Scan

The skill's requirements and behavior are consistent with its stated purpose (local Chrome CDP control); it does not request unrelated credentials or external installs, but it can access and control pages you have open so use it only when you explicitly want that.

Purpose & Capability

Name/description match the implemented behaviour: the script opens a local DevTools WebSocket, lists pages, screenshots, evaluates JS, clicks, navigates, and manages per-tab daemons. Required binary (node) and read access to browser DevToolsActivePort files are expected for this purpose.

Instruction Scope

SKILL.md instructs the agent to run the included CLI (scripts/cdp.mjs) which reads DevToolsActivePort files, creates a runtime directory and sockets, and connects to the browser's local CDP WebSocket. This is necessary for operation but also means the skill can inspect and control content in any open tab once remote debugging is enabled; eval/evalraw commands allow executing arbitrary JS inside pages. The SKILL.md explicitly warns about sensitive content.

Install Mechanism

No install spec; instruction-only with a single Node script. Nothing is downloaded from external URLs during install and no package managers are required, so install risk is low.

Credentials

The skill requires only Node and optionally reads environment variables CDP_PORT_FILE and CDP_HOST (documented in SKILL.md) and uses home/XDG dirs for sockets/cache. It does not request secret tokens or unrelated credentials. Access to the user's home directory and runtime dirs is necessary for socket files and caching.

Persistence & Privilege

Does not request always:true and is not force-enabled. It spawns per-tab daemons and writes runtime files under a user-scoped directory; daemons auto-exit after idle. It does not modify other skills or global agent configuration.

Assessment

This skill legitimately controls a local browser via Chrome's DevTools Protocol. Before installing: (1) Confirm you trust the skill source and review scripts/cdp.mjs (it runs locally and will create sockets/files under your home directory). (2) Only enable Chrome remote debugging when you intend to allow this access — remote debugging + eval/evalraw can execute arbitrary JS in pages (including pages where you're logged in). (3) Avoid using it on sensitive or production accounts unless you understand the implications. (4) If you need stronger assurance, run the script in an isolated account or VM and inspect the code for any unexpected network calls or telemetry.

Chrome CDP

Lightweight Chrome DevTools Protocol CLI. Connects directly via WebSocket, does not need Puppeteer, and works well with large tab counts.

Prerequisites

• Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open chrome://inspect/#remote-debugging and toggle the switch
• Node.js 22+ (uses built-in WebSocket)
• No Python or pip packages are required
• No npm install step is required
• If your browser's DevToolsActivePort is in a non-standard location, set CDP_PORT_FILE to its full path

Quick setup

1. Open Chrome and keep it running.
2. Open chrome://inspect/#remote-debugging.
3. Turn on remote debugging.
4. Keep the browser open while using this skill.
5. Run {baseDir}/scripts/cdp.mjs list to confirm that tabs are visible.

On first access to a tab, Chrome may ask the user to approve debugging access.

Installation

• Recommended: clawhub install chrome-cdp-skill
• Manual: place this skill directory in your OpenClaw workspace skills/ folder
• This skill does not require npm install, Python, or pip packages

Safety

This skill can inspect and control a real local browser session. Commands such as eval, evalraw, click, type, and nav are intentionally powerful and may trigger warnings from security scanners.

Only use this skill when the user explicitly wants you to inspect or operate pages they already have open. Assume those tabs may contain sensitive logged-in content.

The skill only works after the user enables Chrome remote debugging. On first access to a tab, Chrome may ask the user to approve debugging access.

Commands

All commands use {baseDir}/scripts/cdp.mjs. The <target> is a unique targetId prefix from list; copy the full prefix shown in the list output (for example 6BE827FA). The CLI rejects ambiguous prefixes.

List open pages

{baseDir}/scripts/cdp.mjs list

Take a screenshot

{baseDir}/scripts/cdp.mjs shot <target> [file]    # default: screenshot-<target>.png in runtime dir

Captures the viewport only. Scroll first with eval if you need content below the fold. Output includes the page's DPR and coordinate conversion hint (see Coordinates below).

Accessibility tree snapshot

{baseDir}/scripts/cdp.mjs snap <target>

Evaluate JavaScript

{baseDir}/scripts/cdp.mjs eval <target> <expr>

Watch out: avoid index-based selection (querySelectorAll(...)[i]) across multiple eval calls when the DOM can change between them (e.g. after clicking Ignore, card indices shift). Collect all data in one eval or use stable selectors.

Other commands

{baseDir}/scripts/cdp.mjs html    <target> [selector]      # full page or element HTML
{baseDir}/scripts/cdp.mjs nav     <target> <url>           # navigate and wait for load
{baseDir}/scripts/cdp.mjs net     <target>                 # resource timing entries
{baseDir}/scripts/cdp.mjs click   <target> <selector>      # click element by CSS selector
{baseDir}/scripts/cdp.mjs clickxy <target> <x> <y>         # click at CSS pixel coords
{baseDir}/scripts/cdp.mjs type    <target> <text>          # Input.insertText at current focus; works in cross-origin iframes unlike eval
{baseDir}/scripts/cdp.mjs loadall <target> <selector> [ms] # click "load more" until gone (default 1500ms between clicks)
{baseDir}/scripts/cdp.mjs evalraw <target> <method> [json] # raw CDP command passthrough
{baseDir}/scripts/cdp.mjs open    [url]                    # open new tab (each triggers Allow prompt)
{baseDir}/scripts/cdp.mjs stop    [target]                 # stop daemon(s)

Coordinates

shot saves an image at native resolution: image pixels = CSS pixels × DPR. CDP Input events (clickxy etc.) take CSS pixels.

CSS px = screenshot image px / DPR

shot prints the DPR for the current page. Typical Retina (DPR=2): divide screenshot coords by 2.

Tips

• Prefer snap --compact over html for page structure.
• Use type (not eval) to enter text in cross-origin iframes — click/clickxy to focus first, then type.
• Chrome shows an "Allow debugging" modal once per tab on first access. A background daemon keeps the session alive so subsequent commands need no further approval. Daemons auto-exit after 20 minutes of inactivity.