agent-browser

A hardened local browser for AI agents. Zero dependencies. Drives the Chrome you already have over the DevTools Protocol, extracts token-efficient Markdown, and is not trivially flagged as automation.

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

Everything runs locally. No account, no API key, no remote service, no quota.

Why

Feeding an agent raw HTML wastes most of its context. Measured on real pages:

And a browser that announces itself as automation gets blocked, degraded, or served different content — which quietly corrupts whatever the agent concluded.

Related MCP server: Browser-MCP Navigator

Install

As an MCP server

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

Tools: browser_markdown, browser_text, browser_html, browser_links, browser_screenshot, browser_evaluate, browser_accessibility_tree, browser_pdf, browser_probe.

As a library

npm install @truenix/agent-browser

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

As a DSH / Cordis plugin

One-liner (recommended — auto-wires when you mean DSH):

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

Restart dsh — browser_markdown, browser_text, browser_links, browser_evaluate, browser_screenshot, browser_probe appear as native tools. No handler runs on plain npm install; intentional install is required.

Manual (if you prefer to edit the composition yourself):

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

Requires Node ≥ 18 and a Chrome/Chromium install. Then add to the host composition (tools registry lives on host, not per-agent):

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

Short form (when the composition already wraps insert):

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

Env overrides: AGENT_BROWSER_BIN (Chrome binary), AGENT_BROWSER_ENDPOINT (attach to long-lived browser via --endpoint), or config.cli.

CLI

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

Options: --headful, --no-stealth, --block-images, --gpu/--no-gpu, --width, --height, --viewport WxH, --main, --raw, --full, --endpoint <ws>, --timeout, --json, -o.

--endpoint attaches to an already-running browser instead of launching one — useful for reusing a single long-lived browser across many calls.

Bot detection

Run it yourself: npm run test:bot. Latest result:

Plain headless Chrome fails four sannysoft rows (HEADCHR_UA, CHR_MEMORY, WebGL SwiftShader, old UA) and is reported as a bot.

An unreachable detector counts as SKIP, never as a pass, and the gate requires three reachable passes — so a day when the test sites are down cannot be mistaken for success.

Environment matters more than patching

The identical code, measured in two places:

Every CDP-level signal stays clean in both — that part is code, and the code is right. What flips the verdict is the environment: a datacenter ASN plus software rendering trips a weak-signal composite that no amount of fingerprint patching addresses.

This is the honest shape of the problem. Hardening the browser removes the trivial tells. Where you run it decides the rest.

What the hardening does, and why

Every item came from a detector telling us we were wrong:

• No --enable-automation. That flag — which Puppeteer and Playwright add — is what sets navigator.webdriver = true. Raw CDP does not set it, so it stays false with nothing patched.

• No Runtime.enable. It is the loudest CDP tell and powers the classic console/Error.stack detector. Runtime.evaluate works fine without it.

• Window and screen move together. --window-size without --ozone-override-screen-size gives outerWidth > screen.width, which is physically impossible — a stronger signal than plain headless.

• No default device-metrics override. The usual 1280×720 is Playwright's default viewport and detectors flag it by name. Set --viewport only if you need it.

• Real GPU when available, giving a genuine ANGLE (NVIDIA …) renderer instead of SwiftShader.

• UA set at launch, not only over CDP. Emulation.setUserAgentOverride does not reach Web Workers, so a worker keeps reporting the headless UA while the page reports the clean one (hasInconsistentWorkerValues).

• No acceptLanguage override. CDP derives navigator.languages by splitting that header, so "en-US,en;q=0.9" becomes ["en-US","en;q=0.9"] — a q-value where none can legally exist, and another page/worker mismatch. --lang does it correctly.

• Client Hints derived from the binary's own version, so Sec-CH-UA cannot disagree with navigator.userAgent.

• Isolated browser context per session, disposed on close — clean state per task without a second browser process.

The recurring lesson: consistency beats coverage. Four of those are cases where partial spoofing made detection easier, caught only by running real detectors.

Why WebGL spoofing is off by default

spoofWebgl exists and is implemented carefully — a Proxy around native getParameter, so Function.prototype.toString still reports [native code]. It is off, because measurement says it backfires. From test/webgl-spoof-experiment.mjs:

Claiming hardware you do not have fixes one cosmetic row and fails the composite detector: the injected script does not reach Web Workers, so the worker still reports SwiftShader, and MAX_TEXTURE_SIZE stays at the software value while the renderer string claims a discrete GPU.

Honest SwiftShader passes. A convincing lie does not. Give the browser a real GPU instead — it is free.

What this does NOT do

Fingerprint-level detection is the entire scope. It does not defeat, and does not try to:

• TLS/JA3-JA4 and HTTP/2 fingerprinting — decided before any JavaScript runs

• IP reputation — datacenter vs residential ASN, often the real blocker

• Behavioural analysis — mouse paths, timing, dwell

Commercial challenge products lean on those, so "passes the gate" means not trivially flagged as automation, never undetectable. Intended for your own sites, testing, accessibility work, and ordinary agent browsing.

Memory

A Chrome stack costs roughly 450 MB. The lever is architecture, not flags: run one browser and many isolated contexts rather than one browser per task. Start a browser once, then point every call at it with --endpoint / AGENT_BROWSER_ENDPOINT. --block-images helps for text work.

Zero dependencies

dependencies is empty, including the WebSocket transport.

Node's global WebSocket (WHATWG) cannot send request headers, which any authenticated or proxied CDP endpoint needs, and undici is not importable standalone. So src/ws.mjs implements RFC 6455 directly over node:http(s) — handshake, masking, continuation fragments, 64-bit lengths, ping/pong — which is everything CDP requires.

The Markdown converter walks the DOM with an explicit stack, keeping JS call depth at O(1) regardless of nesting, and uses native innerText for leaf-level inline nodes. That makes it both recursion-safe on deeply nested documents and markedly faster on large pages.

Environment

Requirements

Node ≥ 18 and a Chrome/Chromium install. No build step.

Credits

This project's hardening is almost entirely derived from other people's published detection research — see CREDITS.md. Particular thanks to rebrowser-bot-detector, bot.sannysoft.com, deviceandbrowserinfo.com, and Camoufox for showing how this is done properly.

License

MIT