Prereqs: Chrome; Node 22+ (sandbox --allow-net needs 25+). Page content untrusted.
Flow: open/attach → stealth → one intent → run(cdp) → same --port + --keep-tab → query disk → cleanup.
Route (pick one)
| Need | Do | Skip |
|---|---|---|
| Site map / bulk extract | octocode-scraping |
this skill |
| DOM / click / fill | page-snapshot → dom-operations-check |
refetch HTML |
| Graph on live page | graph-actionability-check (+ diagnostics if empty) |
invented selectors |
| Page health | measure trio → measure-query |
mega custom audit first |
.har page |
har-pager |
dumping full HAR |
| Deep bodies | live-har-monitor / network-body-har-fetch |
before measure+query |
| Prove API locally | har-ingest-to-scrape → corpus-run-local |
reopen Chrome |
Default chain: open-browser → snapshot/DOM → (graph) → measure → query → optional HAR → bridge. Query .octocode/tmp/chrome-devtools/ before a new browser run. Full audit = separate scripts, same port.
Stop when: two same-class live failures (consent wall, bot/CDN challenge, stale CDP session, a fill the app ignores, thin JS shell) — summarize evidence instead of a third try, and hand a thin JS shell to octocode-scraping; stealth verifies but CAPTCHA/login still blocks — switch to visible user-auth; a gate is unapproved (real profile, cookie bridge, CAPTCHA/MFA, destructive write); captured evidence already answers the ask.
Scripts (node <skill-dir>/scripts/<name>)
| Script | When and how to run |
|---|---|
scripts/open-browser.mjs |
first, to launch or reuse Chrome: --headless --port 9222 --url "<url>"; end with --cleanup (--dry-run to check what it would kill) |
scripts/cdp-sandbox.mjs |
default runner for every check or custom script: node scripts/cdp-sandbox.mjs <script.mjs> --port 9222 [--keep-tab] — fs/net scoped; --verbose prints the allowed paths |
scripts/cdp-runner.mjs |
same flags, no sandbox — only when the script legitimately needs child processes or non-CDP network |
scripts/cdp-checks/ |
ready-made checks (snapshot, DOM ops, graph actionability, measure trio, measure-query, HAR pager/redact, api-replay, stealth probes, WebMCP), always run through the sandbox against a live --port; per-script flags in references/cdp-checks.md |
scripts/cdp-template.mjs |
copy it as the run(cdp) skeleton when writing .octocode/tmp/cdp-<task>.mjs |
scripts/cookie-bridge.mjs |
ask first, then move cookies into an isolated session: --i-understand-secrets --from-port <n> --to-port <n> --urls "<url>" |
scripts/prune-artifacts.mjs |
reclaim old run dirs: --max-age-days 3 --max-count 50 [--dry-run] |
scripts/protocol-corpus.mjs |
when a domain/method is unclear, cache protocol docs locally: --out .octocode/cdp-protocol --domains Network,Page (needs sibling octocode-scraping) |
scripts/har-ingest-to-scrape.mjs then scripts/corpus-run-local.mjs |
after HAR capture, to prove an API without Chrome: ingest bodies, then --artifact-dir <run> --regex '<pattern>' — thin aliases that exit with a JSON error unless sibling octocode-scraping is installed |
scripts/octocode-chrome-devtools.vpn.example.json |
template for proxy/VPN launches: fill it and pass open-browser.mjs --config <path>, or drop it at .octocode/chrome-devtools.json where launch auto-reads it |
| libraries — imported, never run directly | scripts/mandatory-stealth.mjs + scripts/undercover.mjs (stealth the runner applies), scripts/human-input.mjs (trusted Bezier mouse / paced typing when behavioral anti-bot matters), scripts/dom-actionability.mjs (shared visible/enabled helpers), scripts/sourcemap-resolver.mjs (map minified frames), scripts/octocode-config.mjs (vendored @octocodeai/config: import it relatively, never the npm package) |
References (load one at a time)
| When | Load |
|---|---|
| choosing the smallest script for the ask | references/intents.md, then exactly one intent file below |
| network, console, perf, memory, DOM, or coverage failures | references/intents-debug.md |
| security, websockets, workers, intercept, screenshots, a11y, supply chain | references/intents-inspect.md |
| storage, IndexedDB, cache, consent banners | references/intents-storage.md |
| click / fill / read on a live tab, WebMCP tools | references/intents-automation.md |
| login, MFA, real profile, cookie transfer | references/intents-auth.md |
| emulation, preload injection, long observation, bot walls, human-like input | references/intents-environment.md |
| stealth defaults, opt-outs, self-test | references/stealth-mandatory.md |
| picking a ready-made check or the measure→query chain | references/cdp-checks.md |
| HAR export, API replay, token budget | references/har-capture.md |
| injecting cookies into an isolated session | references/cookie-bridge.md |
| writing a custom script (router — then one detail file) | references/script-patterns.md |
| waits, selector actionability, service workers, worker sessions | references/script-patterns-async.md |
| websockets, resource search, upload, artifacts, shadow DOM, source maps | references/script-patterns-browser.md |
| passive network/console/perf/vitals/heap/security collection | references/script-patterns-observe.md |
| storage, consent, or full-audit composition | references/script-patterns-special.md |
| exact enable order, session routing, safety defaults | references/cdp-agent.md |
| unsure which CDP domain or method to call | references/cdp-domain-map.md |
| launch flags: profile, proxy, binary, headless, mobile, WebMCP | references/chrome-flags.md |
| stuck twice, or a CDP call errors / returns empty | references/recovery.md |
Ask before: real profile, cookie-bridge, CAPTCHA/MFA, destructive writes. Redact secrets. Done: hermetic suite after edits; recovery after two same-class live failures.