Browser Js

Lightweight CDP browser control for AI agents. Token-efficient alternative to the built-in browser tool — 3-10x fewer tokens per interaction. Use when browsi...

Security Scan

The skill appears to be a coherent local Chrome DevTools Protocol (CDP) automation helper; its requirements and behavior align with the stated purpose, though there are a few small metadata mismatches and sensitive capabilities to be aware of.

Purpose & Capability

The skill's name/description match the included code and SKILL.md: it is a CDP-based browser automation CLI. Small mismatches: metadata lists no required binaries/env vars but the tool expects Node (to run node browser.js and npm install) and optionally CDP_URL — these are mentioned in SKILL.md but not declared in the registry 'requires' fields.

Instruction Scope

Runtime instructions stay within the browsing/automation scope (npm install, run node script, connect to local CDP). However the tool exposes powerful actions: page.eval (run arbitrary JS in page), DOM.setFileInputFiles (inject files into file inputs), and coordinate-based Input events (can interact with cross-origin iframes/captchas). These are expected for a browser automation tool but are sensitive because they can act using the browser's signed-in sessions and read/act on page content.

Install Mechanism

There is no packaged install spec — the SKILL.md requires running 'npm install' in the scripts/ dir (uses the well-known npm registry dependency 'ws'). No remote download URLs or archives are present in the install flow. This is a moderate-risk but expected approach for a JS CLI script.

Credentials

The skill declares no required credentials or config paths, which is consistent with a local-only tool. SKILL.md allows overriding the CDP endpoint via CDP_URL (not declared in metadata). Important capability: connecting to a browser profile with --user-data-dir (signed-in sessions) means the tool can act as the signed-in user and access cookies/session data — this is expected for a browser controller but is sensitive and worth explicit consideration.

Persistence & Privilege

Skill is not 'always: true' and does not request elevated or persistent platform privileges. It suggests an optional local alias but does not modify other skills or agent-wide configuration.

Assessment

This skill is coherent with its stated purpose (local CDP-based browser automation), but review these points before installing: - You will need Node/npm to run it; SKILL metadata doesn't list Node as a required binary. Run 'npm install' in the scripts/ directory as instructed. - The tool connects to a Chrome/Chromium instance via the CDP endpoint (default http://127.0.0.1:18800 or set CDP_URL). Ensure the debug port is bound only to localhost and not exposed to the network. - It can use your browser profile (signed-in sessions) and can run arbitrary JS in pages, inject files into file inputs, and dispatch real mouse events — meaning it can read private page content and perform actions as you. Only use it with a browser/profile you trust and not on shared or public machines. - The SKILL.md references CDP_URL but the registry metadata does not declare any env vars; be aware of this mismatch. When creating a local alias, double-check the path used so you don't accidentally point to a different script. - If you plan to allow autonomous agent invocation, consider limiting autonomy or reviewing the code thoroughly; the code uses only local CDP and the npm 'ws' package, but arbitrary page.eval still allows data access. If you want higher assurance, inspect the full scripts/browser.js file locally and run it in a controlled environment first (with a disposable browser profile).

Lightweight CLI that talks to Chrome via CDP (Chrome DevTools Protocol). Returns minimal, indexed output that agents can act on immediately — no accessibility tree parsing, no ref hunting.

Setup

# Install dependency (one-time, in the skill scripts/ dir)
cd scripts && npm install

# Ensure browser is running with CDP enabled.
# With OpenClaw:
#   browser start profile=openclaw
# Or manually:
#   google-chrome --remote-debugging-port=18800 --user-data-dir=~/.browser-data

The tool connects to http://127.0.0.1:18800 by default. Override with CDP_URL env var.

Alias setup (optional)

mkdir -p ~/.local/bin
cat > ~/.local/bin/bjs << 'WRAPPER'
#!/bin/bash
exec node /path/to/scripts/browser.js "$@"
WRAPPER
chmod +x ~/.local/bin/bjs

Commands

bjs tabs                    List open tabs
bjs open <url>              Navigate to URL
bjs tab <index>             Switch to tab
bjs newtab [url]            Open new tab
bjs close [index]           Close tab
bjs elements [selector]     List interactive elements (indexed)
bjs click <index>           Click element by index
bjs type <index> <text>     Type into element
bjs upload <path> [selector] Upload file to input (bypasses OS dialog)
bjs text [selector]         Extract visible page text
bjs html <selector>         Get element HTML
bjs eval <js>               Run JavaScript in page
bjs screenshot [path]       Save screenshot
bjs scroll <up|down|top|bottom> [px]
bjs url                     Current URL
bjs back / forward / refresh
bjs wait <ms>

Coordinate commands (cross-origin iframes, captchas, overlays):
bjs click-xy <x> <y>       Click at page coordinates via CDP Input
bjs click-xy <x> <y> --double   Double-click at coordinates
bjs click-xy <x> <y> --right    Right-click at coordinates
bjs hover-xy <x> <y>       Hover at page coordinates
bjs drag-xy <x1> <y1> <x2> <y2>   Drag between coordinates
bjs iframe-rect <selector> Get iframe bounding box (for click-xy targeting)

How it works

elements scans the page for all interactive elements (links, buttons, inputs, selects, etc.) — including those inside shadow DOM (web components). This means sites like Reddit, GitHub, and other modern SPAs that use shadow DOM are fully supported. The scan recursively pierces all shadow roots.

Returns a compact numbered list:

[0] (link) Hacker News → https://news.ycombinator.com/news
[1] (link) new → https://news.ycombinator.com/newest
[2] (input:text) q
[3] (button) Submit

Then click 3 or type 2 search query — immediately actionable, no interpretation needed.

Auto-indexing: click and type auto-index elements if not already indexed. You can skip calling elements first and go straight to click/type after open. Call elements explicitly when you need to see what's on the page.

After navigation or AJAX changes: Elements get re-indexed automatically on next click/type if stamps are stale. For manual re-index, call elements again.

Real mouse events: click uses CDP Input.dispatchMouseEvent (mousePressed + mouseReleased) instead of JS .click(). This triggers React/Vue/Angular synthetic event handlers that ignore plain .click() calls. Works reliably on SPAs like Instagram, GitHub, LinkedIn.

File uploads

upload uses CDP's DOM.setFileInputFiles to inject files directly into hidden <input type="file"> elements — no OS file picker dialog. Works with Instagram, Twitter, any site with file uploads.

bjs upload ~/photos/image.jpg                    # auto-finds input[type=file]
bjs upload ~/docs/resume.pdf "input.file-drop"   # specific selector

Token efficiency

Approach	Tokens per interaction	Notes
bjs	~50-200	Indexed list, 1-line responses
browser tool (snapshot)	~2,000-5,000	Full accessibility tree
browser tool + thinking	~3,000-8,000	Plus reasoning to find refs

Over a 10-step flow: ~1,500 tokens (bjs) vs ~30,000-80,000 (browser tool).

Typical flow

bjs open https://example.com       # Navigate
bjs elements                        # See what's clickable
bjs click 5                         # Click element [5]
bjs type 12 "hello world"          # Type into element [12]
bjs text                            # Read page content
bjs screenshot /tmp/result.png      # Verify visually

Shadow DOM support

bjs automatically pierces shadow DOM boundaries. Sites built with web components (Reddit, GitHub, etc.) work out of the box — elements, click, type, and text all recurse into shadow roots. No special flags needed.

Coordinate commands (iframes, captchas, overlays)

When you can't use click by index — e.g. the target is inside a cross-origin iframe (captcha checkbox, payment form, OAuth widget) — use coordinate-based commands that dispatch real CDP Input events at the OS level. These bypass all DOM boundaries.

Workflow for clicking inside an iframe:

bjs iframe-rect 'iframe[title*="hCaptcha"]'    # Get bounding box
# Output: x=95 y=440 w=302 h=76 center=(246, 478)

bjs click-xy 125 458                            # Click checkbox position

iframe-rect returns the iframe's position on the page. Add offsets to target specific elements inside it (e.g. a checkbox is typically near the left side).

Other uses:

• hover-xy — trigger hover menus, tooltips that need mouse position
• drag-xy — slider controls, drag-and-drop, canvas interactions
• click-xy --double — double-click to select text, expand items
• click-xy --right — context menus

When to use coordinate commands vs click:

• click <index> — always preferred when the element shows up in elements
• click-xy — only when the target is inside a cross-origin iframe or otherwise unreachable by DOM indexing

Tips

• elements with a CSS selector narrows scope: bjs elements ".modal"
• eval runs arbitrary JS and returns the result — use for custom extraction
• text caps at 8KB — enough for most pages, won't blow up context
• html <selector> caps at 10KB — for inspecting specific elements
• Pipe through grep to filter: bjs elements | grep -i "submit\|login"