CLI browser navigation for LLM Agents instead of MCP (from topic mariozechner.at)

README.md

Browser Tools

Minimal CDP tools for collaborative site exploration.

Start Chrome

./browser-tools-start.js              # Fresh profile
./browser-tools-start.js --profile    # Copy your profile (cookies, logins)

Start Chrome on :9222 with remote debugging.

Navigate

./browser-tools-nav.js https://example.com
./browser-tools-nav.js https://example.com --new

Navigate current tab or open new tab.

Evaluate JavaScript

./browser-tools-eval.js 'document.title'
./browser-tools-eval.js 'document.querySelectorAll("a").length'

Execute JavaScript in active tab (async context).

Screenshot

./browser-tools-screenshot.js

Screenshot current viewport, returns temp file path.

Pick Elements

./browser-tools-pick.js "Click the submit button"

Interactive element picker. Click to select, Cmd/Ctrl+Click for multi-select, Enter to finish.

alias.sh

alias cl="PATH=$PATH:~/agent-tools/browser-tools:<other-tool-dirs> && claude --dangerously-skip-permissions"

browser-tools-evaluate.js

#!/usr/bin/env node

import puppeteer from "puppeteer-core";

const code = process.argv.slice(2).join(" ");
if (!code) {
	console.log("Usage: eval.js 'code'");
	console.log("\nExamples:");
	console.log('  eval.js "document.title"');
	console.log('  eval.js "document.querySelectorAll(\'a\').length"');
	process.exit(1);
}

const b = await puppeteer.connect({
	browserURL: "http://localhost:9222",
	defaultViewport: null,
});

const p = (await b.pages()).at(-1);

if (!p) {
	console.error("✗ No active tab found");
	process.exit(1);
}

const result = await p.evaluate((c) => {
	const AsyncFunction = (async () => {}).constructor;
	return new AsyncFunction(`return (${c})`)();
}, code);

if (Array.isArray(result)) {
	for (let i = 0; i < result.length; i++) {
		if (i > 0) console.log("");
		for (const [key, value] of Object.entries(result[i])) {
			console.log(`${key}: ${value}`);
		}
	}
} else if (typeof result === "object" && result !== null) {
	for (const [key, value] of Object.entries(result)) {
		console.log(`${key}: ${value}`);
	}
} else {
	console.log(result);
}

await b.disconnect();

browser-tools-navigate.js

#!/usr/bin/env node

import puppeteer from "puppeteer-core";

const url = process.argv[2];
const newTab = process.argv[3] === "--new";

if (!url) {
	console.log("Usage: nav.js <url> [--new]");
	console.log("\nExamples:");
	console.log("  nav.js https://example.com       # Navigate current tab");
	console.log("  nav.js https://example.com --new # Open in new tab");
	process.exit(1);
}

const b = await puppeteer.connect({
	browserURL: "http://localhost:9222",
	defaultViewport: null,
});

if (newTab) {
	const p = await b.newPage();
	await p.goto(url, { waitUntil: "domcontentloaded" });
	console.log("✓ Opened:", url);
} else {
	const p = (await b.pages()).at(-1);
	await p.goto(url, { waitUntil: "domcontentloaded" });
	console.log("✓ Navigated to:", url);
}

await b.disconnect();

browser-tools-pick.js

#!/usr/bin/env node

import puppeteer from "puppeteer-core";

const message = process.argv.slice(2).join(" ");
if (!message) {
	console.log("Usage: pick.js 'message'");
	console.log("\nExample:");
	console.log('  pick.js "Click the submit button"');
	process.exit(1);
}

const b = await puppeteer.connect({
	browserURL: "http://localhost:9222",
	defaultViewport: null,
});

const p = (await b.pages()).at(-1);

if (!p) {
	console.error("✗ No active tab found");
	process.exit(1);
}

// Inject pick() helper into current page
await p.evaluate(() => {
	if (!window.pick) {
		window.pick = async (message) => {
			if (!message) {
				throw new Error("pick() requires a message parameter");
			}
			return new Promise((resolve) => {
				const selections = [];
				const selectedElements = new Set();

				const overlay = document.createElement("div");
				overlay.style.cssText =
					"position:fixed;top:0;left:0;width:100%;height:100%;z-index:2147483647;pointer-events:none";

				const highlight = document.createElement("div");
				highlight.style.cssText =
					"position:absolute;border:2px solid #3b82f6;background:rgba(59,130,246,0.1);transition:all 0.1s";
				overlay.appendChild(highlight);

				const banner = document.createElement("div");
				banner.style.cssText =
					"position:fixed;bottom:20px;left:50%;transform:translateX(-50%);background:#1f2937;color:white;padding:12px 24px;border-radius:8px;font:14px sans-serif;box-shadow:0 4px 12px rgba(0,0,0,0.3);pointer-events:auto;z-index:2147483647";

				const updateBanner = () => {
					banner.textContent = `${message} (${selections.length} selected, Cmd/Ctrl+click to add, Enter to finish, ESC to cancel)`;
				};
				updateBanner();

				document.body.append(banner, overlay);

				const cleanup = () => {
					document.removeEventListener("mousemove", onMove, true);
					document.removeEventListener("click", onClick, true);
					document.removeEventListener("keydown", onKey, true);
					overlay.remove();
					banner.remove();
					selectedElements.forEach((el) => {
						el.style.outline = "";
					});
				};

				const onMove = (e) => {
					const el = document.elementFromPoint(e.clientX, e.clientY);
					if (!el || overlay.contains(el) || banner.contains(el)) return;
					const r = el.getBoundingClientRect();
					highlight.style.cssText = `position:absolute;border:2px solid #3b82f6;background:rgba(59,130,246,0.1);top:${r.top}px;left:${r.left}px;width:${r.width}px;height:${r.height}px`;
				};

				const buildElementInfo = (el) => {
					const parents = [];
					let current = el.parentElement;
					while (current && current !== document.body) {
						const parentInfo = current.tagName.toLowerCase();
						const id = current.id ? `#${current.id}` : "";
						const cls = current.className
							? `.${current.className.trim().split(/\s+/).join(".")}`
							: "";
						parents.push(parentInfo + id + cls);
						current = current.parentElement;
					}

					return {
						tag: el.tagName.toLowerCase(),
						id: el.id || null,
						class: el.className || null,
						text: el.textContent?.trim().slice(0, 200) || null,
						html: el.outerHTML.slice(0, 500),
						parents: parents.join(" > "),
					};
				};

				const onClick = (e) => {
					if (banner.contains(e.target)) return;
					e.preventDefault();
					e.stopPropagation();
					const el = document.elementFromPoint(e.clientX, e.clientY);
					if (!el || overlay.contains(el) || banner.contains(el)) return;

					if (e.metaKey || e.ctrlKey) {
						if (!selectedElements.has(el)) {
							selectedElements.add(el);
							el.style.outline = "3px solid #10b981";
							selections.push(buildElementInfo(el));
							updateBanner();
						}
					} else {
						cleanup();
						const info = buildElementInfo(el);
						resolve(selections.length > 0 ? selections : info);
					}
				};

				const onKey = (e) => {
					if (e.key === "Escape") {
						e.preventDefault();
						cleanup();
						resolve(null);
					} else if (e.key === "Enter" && selections.length > 0) {
						e.preventDefault();
						cleanup();
						resolve(selections);
					}
				};

				document.addEventListener("mousemove", onMove, true);
				document.addEventListener("click", onClick, true);
				document.addEventListener("keydown", onKey, true);
			});
		};
	}
});

const result = await p.evaluate((msg) => window.pick(msg), message);

if (Array.isArray(result)) {
	for (let i = 0; i < result.length; i++) {
		if (i > 0) console.log("");
		for (const [key, value] of Object.entries(result[i])) {
			console.log(`${key}: ${value}`);
		}
	}
} else if (typeof result === "object" && result !== null) {
	for (const [key, value] of Object.entries(result)) {
		console.log(`${key}: ${value}`);
	}
} else {
	console.log(result);
}

await b.disconnect();

browser-tools-screenshot.js

#!/usr/bin/env node

import { tmpdir } from "node:os";
import { join } from "node:path";
import puppeteer from "puppeteer-core";

const b = await puppeteer.connect({
	browserURL: "http://localhost:9222",
	defaultViewport: null,
});

const p = (await b.pages()).at(-1);

if (!p) {
	console.error("✗ No active tab found");
	process.exit(1);
}

const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
const filename = `screenshot-${timestamp}.png`;
const filepath = join(tmpdir(), filename);

await p.screenshot({ path: filepath });

console.log(filepath);

await b.disconnect();

browser-tools-start.js

#!/usr/bin/env node

import { spawn, execSync } from "node:child_process";
import puppeteer from "puppeteer-core";

const useProfile = process.argv[2] === "--profile";

if (process.argv[2] && process.argv[2] !== "--profile") {
	console.log("Usage: start.ts [--profile]");
	console.log("\nOptions:");
	console.log("  --profile  Copy your default Chrome profile (cookies, logins)");
	console.log("\nExamples:");
	console.log("  start.ts            # Start with fresh profile");
	console.log("  start.ts --profile  # Start with your Chrome profile");
	process.exit(1);
}

// Kill existing Chrome
try {
	execSync("killall 'Google Chrome'", { stdio: "ignore" });
} catch {}

// Wait a bit for processes to fully die
await new Promise((r) => setTimeout(r, 1000));

// Setup profile directory
execSync("mkdir -p ~/.cache/scraping", { stdio: "ignore" });

if (useProfile) {
	// Sync profile with rsync (much faster on subsequent runs)
	execSync(
		'rsync -a --delete "/Users/badlogic/Library/Application Support/Google/Chrome/" ~/.cache/scraping/',
		{ stdio: "pipe" },
	);
}

// Start Chrome in background (detached so Node can exit)
spawn(
	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
	["--remote-debugging-port=9222", `--user-data-dir=${process.env["HOME"]}/.cache/scraping`],
	{ detached: true, stdio: "ignore" },
).unref();

// Wait for Chrome to be ready by attempting to connect
let connected = false;
for (let i = 0; i < 30; i++) {
	try {
		const browser = await puppeteer.connect({
			browserURL: "http://localhost:9222",
			defaultViewport: null,
		});
		await browser.disconnect();
		connected = true;
		break;
	} catch {
		await new Promise((r) => setTimeout(r, 500));
	}
}

if (!connected) {
	console.error("✗ Failed to connect to Chrome");
	process.exit(1);
}

console.log(`✓ Chrome started on :9222${useProfile ? " with your profile" : ""}`);