Puppeteer-core / CDP — control a real Chrome browser via Chrome DevTools Protocol. For automating external websites, scraping, and cross-browser testing.
Playwright — testing our own applications with reliable selectors and auto-waiting.

Requirements

Both capabilities require the CDP proxy to be running on the host:

# Install and start the CDP proxy (once per host)
bash host-bridge/install-host-bridge.sh

The proxy requires CDP_PROXY_TOKEN (>=16 chars) or a token file at ~/.molecule-cdp-proxy-token. For local development without a token, bind explicitly to loopback: BIND_ADDR=127.0.0.1 node host-bridge/cdp-proxy.cjs --dev-mode.

Puppeteer (external sites)

Connect via puppeteer.connect() using the bundled lib/connect.js helper. Always pass defaultViewport: null to avoid coordinate corruption (see known-issue KI-001).

const { connect } = require('./lib/connect.js');
const browser = await connect();
const page = await browser.newPage();
// ...
await browser.disconnect();  // NOT browser.close() — see KI-004

Playwright (internal app testing)

For testing Molecule AI's own applications. Use Playwright's built-in selectors and auto-wait for reliable tests.

Install

Plugin setup installs the lockfile-pinned puppeteer-core dependency into this plugin directory. It does not require a global npm prefix or root access, and a failed install stops setup instead of leaving the plugin partially available.

In org template (org.yaml)

plugins:
  - browser-automation

From Gitea source

gitea://molecule-ai/molecule-ai-plugin-browser-automation

Runtime

claude_code — primary

Skills

browser-automation — Puppeteer/CDP skill
browser-testing — Playwright skill

Known issues

See known-issues.md.

KI-002: The Chrome profile is shared across agents — use separate --user-data-dir for isolation
KI-003: For local dev without a token, use loopback-bound --dev-mode

README.md

browser-automation