# Tkersey Dotfiles Web Browser > Web Browser - Skill: `tomevault-io/tkersey-dotfiles-web-browser` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/tkersey-dotfiles-web-browser` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/tkersey-dotfiles-web-browser/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/tkersey-dotfiles-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 ```bash # 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. ```bash ./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: ```bash 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 --new` when you want deterministic targeting. - If actions hit the “wrong” tab, close extra tabs or open a fresh one. ## Common commands ```bash # 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 ```bash # 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: ```bash 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` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/tkersey) — claim your Tome and manage your conversions.