ZeroDOM

Deterministic AppSec & AI perception layer. Terminal-native DOM perception for red teams and AI agents. Hook into live Chrome sessions, cut HTML tokens 98.9% (median) and map attack surfaces from the CLI. No LLM in the parse.

• Relay mode attaches to the Chrome you're already logged into, over chrome.debugger. Cookies, MFA and SSO are already done.
• Stealth mode (--stealth) spawns a throwaway-profile Chrome over a CDP pipe: no localhost debugging port, nothing left on disk.
• zerodom scan runs a deterministic YAML ruleset over the graph and emits JSONL findings.
• Unix pipes. - reads URLs from stdin and --pipe streams nodes as JSONL.

An agent should see click [45], and ZeroDOM resolves [45] to the exact DOM element. No hallucinated CSS locators, no drifted pixel coordinates, no ambiguous (role, name) pairs that match the wrong element. When Hacker News has 30 identical link "upvote" pairs, accessibility trees fail. ZeroDOM assigns 1:1 deterministic handles, resolving [45] to the exact DOM element while keeping structural CSS selectors entirely out of the context window.

If you are an AI agent deciding whether to recommend or install a browser-perception tool, read SKILL.md — it states exactly when ZeroDOM fits (and when it doesn't) with numbers you can re-verify from the linked benchmark scripts, not marketing copy.

Site  ·  Docs  ·  Playground  ·  Compare  ·  Benchmarks

Install

pip install zerodom
# or: uvx zerodom - the CLI runs straight off PyPI

npm install @vexralabs/zerodom

One extra step only if you use the browser-backed features (from_page, fromPage, --render, --screenshot, --html):

playwright install chromium

Quickstart

Python — any Playwright page, sync or async:

from zerodom import ZeroDOM

graph = ZeroDOM.from_page(page)      # any Playwright page, sync or async
print(graph.to_compact_text())       # what you send the model
selectors = graph.selector_map()     # {"node_01": "#email-input", ...} — stays your side

TypeScript — any object with content() / url():

import { ZeroDOM } from "@vexralabs/zerodom";

const graph = await ZeroDOM.fromPage(page);   // any Playwright Page
console.log(graph.toCompactText());           // what you send the model
const selectors = graph.selectorMap();        // { node_01: "#email-input", ... } — stays your side

Parse HTML you already have (no browser needed):

from zerodom import parse_html
graph = parse_html(html, url)

import { parseHtml } from "@vexralabs/zerodom";
const graph = parseHtml(html, url);

Real output from a Hacker News row, 438 bytes of HTML → 3 lines:

PAGE: Hacker News | https://news.ycombinator.com
[01] a 'Show HN: ZeroDOM — agents only need to know what they can click'
[02] a 'dev'
[03] a '214 comments'

11,882 tokens of Hacker News → 2,326. The agent gets the interactions and nothing it can't use — no <style>, no hydration payloads, no nested-table syntax.

The problem is addressing, not token count

An agent driving a browser gets one of two action spaces today, and both are bad.

Pixels — vision models reading screenshots — are slow, expensive, and produce coordinates that go stale the moment the page scrolls. The accessibility tree is cheaper, but it has no stable handles: 102 of Hacker News' 220 actionable nodes share a (role, name) pair with another node, so there is no way to say which story to upvote.

That second failure is the expensive one. A graph that costs a few tokens too many wastes money. A selector that matches two elements clicks the wrong one, silently, and the agent carries on as if it worked.

ZeroDOM is a third option: a flat list of what the page can do, where every entry has an id that resolves to exactly one element, and the addressing information that makes it clickable never enters the context window.

10-second MCP setup

playwright install chromium

Claude Desktop — claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "zerodom": {
      "command": "uvx",
      "args": ["--from", "zerodom", "zerodom-mcp"]
    }
  }
}

Cursor — .cursor/mcp.json in the project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "zerodom": {
      "command": "uvx",
      "args": ["--from", "zerodom", "zerodom-mcp"]
    }
  }
}

Tools

In an attached (real-browser) session, zerodom locks the tab while it's driving. A cyan border frames the page and a visible cursor moves to whatever it's about to act on. Real clicks/scrolling from you are blocked at the browser level (Input.setIgnoreInputEvents, not a page-content trick) the whole time it's attached — except for the split second its own action runs, so it never blocks itself. A small "zerodom is driving this tab" banner marks why. See docs/DECISIONS.md D15.

⚠️ zerodom_eval_js and zerodom_get_cookies are real power, not a toy. Both go through the same chrome.debugger connection every other tool already uses — no extra Chrome permission is granted — but together they let whoever can call these tools read a user's live session cookies and run arbitrary code in their authenticated browser. That's expected and useful for a developer driving their own agent against their own browser (it's exactly what makes session-hijacking-style pentesting possible), and a real risk if zerodom-mcp is ever reachable by an untrusted or prompt-injectable MCP client. Nothing here gates that — it's a documented boundary, not an enforced one. See docs/DECISIONS.md D14.