tkersey/web-browser

Web Browser

When to use

• Navigate or interact with live websites.
• Click buttons, fill forms, or extract page content.
• Evaluate JavaScript in a real browser context.
• Capture screenshots for debugging or review.
• UI validation and smoke testing in a real browser.
• Measure and gate latency regressions in web-browser tools with the local benchmark scripts.

Requirements

• Run commands from codex/skills/web-browser/ (so ./tools/*.js resolves).
• Node.js (ESM + top-level await) and repo deps installed (notably puppeteer-core).
• Chrome/Chromium installed, or set CODEX_CHROME_PATH.

Quick start

# Start Chrome with CDP on :9222
./tools/start.js

# Safer (recommended on your laptop): avoid killing an existing Chrome session
./tools/start.js --no-kill

# Open a deterministic tab, then operate on it
./tools/nav.js https://example.com --new
./tools/eval.js 'document.title'
./tools/screenshot.js

Loop: take small steps → inspect state (eval.js / screenshot.js) → repeat.

Performance pass ($lift)

Use this when optimizing or validating web-browser tool latency.

./tools/start.js --no-kill
./tools/nav.js https://example.com --new

cd tools
npm run -s bench:all -- --warmup 5 --samples 30 --screenshot-samples 20

For stricter CI-style gating, add p95 budgets:

cd tools
npm run -s bench:all -- \
  --warmup 5 \
  --samples 30 \
  --screenshot-samples 20 \
  --budget-nav-p95-ms 310 \
  --budget-eval-p95-ms 220 \
  --budget-screenshot-p95-ms 320 \
  --budget-start-p95-ms 140

Configuration

• Flags
  • start.js: --port, --user-data-dir, --chrome-path, --profile, --no-kill
  • nav.js / eval.js / screenshot.js / pick.js: --port, --browser-url
• Environment
  • CODEX_BROWSER_URL: CDP URL (used when no CLI --port/--browser-url)
  • CODEX_BROWSER_PORT (alias: CODEX_CDP_PORT): CDP port for localhost
  • CODEX_BROWSER_USER_DATA_DIR: Chrome user data dir (used by start.js)
  • CODEX_CHROME_PATH (aliases: CHROME_PATH, PUPPETEER_EXECUTABLE_PATH): Chrome/Chromium executable

Targeting (active tab)

All tools operate on the “active tab”, defined as the last page returned by puppeteer.pages() (roughly: the most recently opened tab).

• Prefer ./tools/nav.js <url> --new when you want deterministic targeting.
• If actions hit the “wrong” tab, close extra tabs or open a fresh one.

Common commands

# See all options (safe; does not start/kill Chrome)
./tools/start.js --help

# Use a non-default port
./tools/start.js --port 9223 --no-kill
./tools/nav.js --port 9223 https://example.com --new

# Or configure once via env
export CODEX_BROWSER_URL=http://localhost:9223
./tools/eval.js 'document.title'

# Wait for a selector (polling with timeout; good for SPAs)
./tools/eval.js '(async () => { for (let i = 0; i < 50; i++) { const el = document.querySelector("button[type=submit]"); if (el) return true; await new Promise(r => setTimeout(r, 100)); } return false; })()'

# Screenshot current viewport
# Prints a PNG filepath in your system temp dir
./tools/screenshot.js

# Pick elements interactively
# Prints tag/id/class/text/html/parents for one element (or many via Cmd/Ctrl+click)
./tools/pick.js "Click the submit button"

Tip: use pick.js to inspect attributes/text, then craft a selector for eval.js.

Recipes

# Scrape structured data (return an array of objects for readable output)
./tools/eval.js 'Array.from(document.querySelectorAll("a"), a => ({ href: a.href, text: a.textContent?.trim() }))'

• Login flows
  • Dedicated automation profile: run ./tools/start.js, log in once, then reuse the persisted profile in your user-data-dir (default: ~/.cache/scraping).
  • Default-profile bootstrap: run ./tools/start.js --profile when you truly need existing cookies/logins.

Security & privacy

• ./tools/start.js --profile uses rsync -a --delete to copy your default Chrome profile into your user-data-dir (cookies/sessions/PII).
• Treat your user-data-dir (default: ~/.cache/scraping) as sensitive; avoid on shared machines and delete it when done if needed.

Troubleshooting

• ✗ Failed to connect to Chrome via CDP: run ./tools/start.js (or set CODEX_BROWSER_URL/--port to match your Chrome).
• ✗ No active tab found: open a page first (e.g., ./tools/nav.js https://example.com --new).
• Port 9222 is busy: pick a new one (./tools/start.js --port 9223).
• Selector flakiness: use the polling pattern above; SPAs often need a wait after domcontentloaded.
• Chrome path not found: set CODEX_CHROME_PATH or pass --chrome-path.

Pitfalls

• ./tools/start.js defaults to killing Chrome processes (use --no-kill to avoid this).
• Use single quotes around JS to avoid shell-escaping issues.

Prove $lift uses Zig

When you need objective proof that the local $lift tooling is Zig-based:

bench_stats --help 2>&1 | sed -n '1,6p'
perf_report --help 2>&1 | sed -n '1,6p'
brew cat tkersey/tap/lift | rg -n 'depends_on \"zig\" => :build|build-exe|bench_stats.zig|perf_report.zig'

References

• codex/skills/web-browser/tools/start.js
• codex/skills/web-browser/tools/nav.js
• codex/skills/web-browser/tools/eval.js
• codex/skills/web-browser/tools/screenshot.js
• codex/skills/web-browser/tools/pick.js
• codex/skills/web-browser/tools/bench-eval.js
• codex/skills/web-browser/tools/bench-all.js