Chrome Use

Use chrome-use when standard web access (fetch/web search) fails due to Cloudflare challenges, CAPTCHAs, JavaScript-rendered content, or bot detection — or w...

Security Scan

The skill largely matches its stated purpose (control a real Chrome via an extension) but contains several concerning and inconsistent choices — notably use of the user's real Chrome profile, an unauthenticated WebSocket server that binds publicly by default, and documentation/code mismatches — that raise privacy and exposure risks.

Purpose & Capability

The name/description (control Chrome via the debugger API to bypass anti-bot) aligns with the code: an extension (debugger permission) + a local server + Node client that issues navigation/evaluate/click/fill/screenshot commands. However the implementation intentionally accesses the user's Chrome profile directory and requests wide host_permissions which are stronger than what most automation tasks strictly require (they may be justified for 'stealth' but are disproportionate to simple page retrieval).

Instruction Scope

Runtime instructions and code direct launching Chrome using the user's profile directory and loading a persistent extension with broad permissions; they instruct waiting, manual extension installation, using launchChrome() only, and disallow other debug methods. The skill (and extension) can read/execute arbitrary JS in pages, access all http(s) sites, take screenshots and obtain page HTML — effectively full access to browsing data and session state. SKILL.md and extension README contain inconsistencies (README refers to a Python server while the packaged server is Node), which suggests stale or copied docs and reduces trust in the instructions.

Install Mechanism

No remote downloads or unusual installers are used: code is bundled with the skill, and npm install is the only dependency-step. That is lower risk vs fetching arbitrary binaries. Still, there is no formal install spec in the registry metadata and the extension must be manually loaded into Chrome (persistent browser change).

Credentials

The skill requests no cloud credentials, which is appropriate, but it programmatically uses the user's Chrome profile (HOME/LOCALAPPDATA paths) and launches Chrome with --user-data-dir pointing at that profile. This grants the skill and extension access to cookies, logged-in sessions, and potentially other sensitive browser-stored data. The extension's manifest requests debugger, tabs, activeTab, nativeMessaging and host permissions for all http/https sites — broad permissions that are plausible for a stealth automation tool but pose high privacy risk and are disproportionate unless the user explicitly intends to expose their profile/state.

Persistence & Privilege

The extension is installed manually and then persists in Chrome with broad permissions (host_permissions and debugger). That gives long-term, browser-level privileges outside the agent; combined with the skill's server it increases blast radius. The Node WebSocket server binds to a port (9224) and accepts extension connections; the code uses new WebSocketServer({ port }) without a host option, which typically binds to all interfaces rather than localhost, meaning the service may be reachable from the network if the machine is not firewalled. The skill itself does not modify other skills, and always:false mitigates forced inclusion, but persistent browser extension + network-exposed server is a meaningful privilege.

What to consider before installing

This skill appears to do what it claims (control a real Chrome via an extension) but contains design choices that raise privacy and exposure risks. Before installing or using it, consider the following: - Do not run this against your regular Chrome profile. The bridge launches Chrome with --user-data-dir pointed at your normal profile, which exposes cookies, sessions, extensions, cached credentials and other private data. Use a disposable / new profile or a VM. - The extension has powerful permissions (debugger, tabs, host permissions for all sites). Installing it permanently grants it broad access to your browsing activity; review the extension code yourself and be prepared to remove it after use. - The WebSocket server (port 9224) is unauthenticated and the Node code uses new WebSocketServer({ port }) which typically binds to all network interfaces. If your machine is on a network, other hosts could reach that port. Either ensure it binds only to localhost or block the port in your firewall before launching. - The repo docs are inconsistent (README mentions Python while the packaged server is Node) — this suggests stale/copied documentation. Audit the code paths you plan to use and validate behavior locally. - If you need to use this skill, run it in an isolated environment (separate OS user, container, or VM), avoid loading your main Chrome profile, inspect the extension files, and consider adding an authenticated local proxy (or modify the server to bind to localhost only) before granting it access. What would raise confidence to 'benign': explicit localhost-only binding for the WebSocket server, removing use of the real profile (use a temporary profile by default), narrower host permissions, clearer docs matching the packaged language, and an authentication mechanism for the local control channel.

Chrome Use OpenClaw Skill

Control your local Chrome browser via chrome.debugger API using a Chrome extension. Provides Playwright-like functionality with full browser control using your existing Chrome profile, with improved stealth against bot detection.

How to Use (Read First)

⚠️ Non-Headless Mode Required

Do NOT use headless Chrome. Cloudflare and anti-bot systems detect and block headless browsers. Always launch Chrome with the built-in launchChrome() method. If running in a headless environment (no display), Chrome must still be launched in non-headless mode — the extension and debugger API require it.

⚠️ Initialization Sequence

The extension requires 15 seconds to initialize after Chrome starts. Calling connect() too early will fail.

// Import from ./index.js (relative path, NOT 'chrome-use')
import { connect, navigate, evaluate, click, fill, screenshot, disconnect } from './index.js';
import { launchChrome } from './index.js';

// Step 1: Launch Chrome with extension
await launchChrome();

// Step 2: Wait 15 seconds for extension service worker to initialize
await new Promise(r => setTimeout(r, 15000));

// Step 3: Connect to Chrome
await connect();

// Step 4: Use
await navigate('https://example.com');

// ... do things ...

// Disconnect when done
disconnect();

When implementing: always use the built-in launchChrome() function — never spawn Chrome yourself or use other launch methods.

Rules

• Always import from ./index.js (relative path), NOT from 'chrome-use'
• Do NOT run google-chrome or chromium commands directly
• Do NOT use CDP protocol or chrome.debugger directly
• Always wait 15 seconds after launchChrome() before calling connect()
• Chrome can be running already — launchChrome() will open a new window if Chrome is already running
• If port 9224 is in use: run fuser -k 9224/tcp first

Features

• Stealth First: Uses chrome.debugger API via extension to evade anti-bot detection (Cloudflare, reCAPTCHA, fingerprinting)
• Auto WebSocket Server: Automatically starts and manages WebSocket server for extension communication
• Real Browser Rendering: Access JavaScript-rendered content and SPAs that standard search cannot
• Direct Search Engine Access: Query Google, Bing, etc. as a real user - returns unfiltered, real-time results
• Full Browser Control - Navigate, click, fill, hover, scroll, screenshot, execute JavaScript
• Tab Management - List, create, close, and switch tabs
• Cross-Platform - Supports macOS, Windows, and Linux

Installation (One-time)

Chrome extension must be installed manually (one-time):

1. Open Chrome → chrome://extensions/
2. Enable "Developer mode" (toggle in top right)
3. Click "Load unpacked"
4. Select the extension/ folder in the skill directory

After this, the extension loads automatically every time Chrome starts — no need to reload it each session.

Install npm dependencies:

cd ~/workspace/skills/chrome-use && npm install

Functions

Connection Management

connect()

Connect to Chrome via extension WebSocket server. Starts the WebSocket server and waits for the extension to connect. Does NOT launch Chrome - you must call launchChrome() first.

await launchChrome();
await new Promise(r => setTimeout(r, 15000));
await connect();
// Returns: { status: "connected", mode: "debugger", port: 9224, extension_installed: true, tab_id: 12345 }

disconnect()

Disconnect from Chrome browser. Does NOT close Chrome - leaves it running.

isConnected()

Check if currently connected to Chrome extension. Returns: boolean

launchChrome()

Launch Chrome with the extension loaded. After calling this, you MUST wait 15 seconds before calling connect().

{ status: "launched", pid: 12345 }

Page Operations

navigate(url)

Navigate to a URL.

evaluate(script)

Execute JavaScript synchronously.

const title = await evaluate("document.title");

getHtml()

Get the page HTML. Returns: string

screenshot(fullPage?)

Take a screenshot. fullPage (boolean, optional): Capture full page or just viewport (default: false). Returns: string (Base64 PNG)

Element Interaction

click(selector)

Click an element using CSS selector.

fill(selector, value)

Input text into an element.

Tab Management

listTabs()

List all open tabs.

[
  { id: 708554825, title: "Google", url: "https://google.com", active: true },
  { id: 708554826, title: "Example", url: "https://example.com", active: false }
]

switchTab(tabId)

Switch to a different tab.

closeTab(tabId)

Close a tab.

newTab(url?)

Create a new tab.

Common Mistakes

Don't Do This	Why
import ... from 'chrome-use'	Not a npm package. Use from './index.js'
google-chrome --load-extension=...	Use launchChrome() instead
npm install chrome-use	Not published to npm
Calling connect() immediately after launchChrome()	Always wait 15 seconds first
Port 9224 in use	Run fuser -k 9224/tcp first

Troubleshooting

connect() fails

1. Did you wait 15 seconds after launchChrome()?
2. Is port 9224 free? (fuser -k 9224/tcp)
3. Is the extension installed in Chrome?

Port 9224 already in use

fuser -k 9224/tcp

Notes

• Node.js starts a WebSocket server (port 9224) via connect(); the Chrome extension connects to Node.js as a WebSocket client, then uses chrome.debugger API to control Chrome
• disconnect() does NOT close Chrome by default
• All selectors use CSS selector syntax