Skip to main content
Glama

Page-Map — open-source, low-cost browser control for AI agents

CI License: MIT

Page-Map lets any AI agent — Claude Code, Cursor, Codex, VS Code, any MCP client — read and control your real Chrome through the page's structure instead of screenshots. It is free, runs locally, needs no API key, and several agents can work in parallel tabs.

Looking for a cheaper alternative to screenshot-based computer use or browser agents, a multi-agent browser tool, or zero-cost replay of repeated browser tasks? That's what this is.

Same 5 real tasks, same Chrome

Page-Map

Screenshot + pixel-click loop

Success

15/15

12/15 (fails dropdowns)

Cost

$0.40

$1.27 (3.2× more)

Time

132 s

246 s (1.9× slower)

5 tasks in parallel

13.4 s

not possible (needs the one visible tab)

Repeating a task

$0, < 3 s (recipe replay)

full price every time

Measured with scripts/compare.js (Claude via claude -p, 3 runs per task, answers checked against live sources). Reproduce it yourself.

AI agent ──MCP──► mcp/server.js ──private socket──► native host ──native messaging──► extension ──► your tabs

The agent is the brain; Page-Map is its eyes and hands. Scripts do everything deterministic; the agent only decides.

Install (macOS / Linux, Chrome)

git clone https://github.com/xlucifer65/page-map.git && cd page-map
npm install
npm run install-host          # registers the native host with Chrome
npm run install-host -- --browser brave   # or chromium | edge | all (default: chrome)
  1. Chrome → chrome://extensions → Developer mode → Load unpacked → pick ./extension (or unzip the latest release). The manifest key pins the id to hmoipddaijkfcidjilmbbiodbmgedbjm.

  2. Add the MCP server to your agent:

    Agent

    Command / config

    Claude Code

    claude mcp add -s user page-map -- node "$PWD/mcp/server.js"

    Cursor / VS Code / others

    MCP server, stdio: command node, args ["<repo>/mcp/server.js"]

  3. Ask your agent: "Open news.ycombinator.com and tell me the top story."

Windows isn't supported yet (needs a registry-based host install) — PRs welcome.

Related MCP server: chrome-browser-bridge

Tools

tool

what it does

navigate(url)

opens a page; returns its outline + text preview + [site memory] (known elements, recipes)

outline

title, landmarks, headings with refs, element counts, ~700-char text preview

read_text(query?)

main content as markdown; query returns only matching lines ("binomial name" → Binomial name | Columba livia)

find(query, role?)

best matching elements with refs

read_page

interactive elements on screen: ref role "name" =value [flags]

click / type / select_option

by ref or label (type(label="Search", text="…", submit=true)); returns only what changed, or the new page if it navigated

fill_form(fields, submit)

fills text fields, dropdowns (native and custom) and checkboxes by label in one call

batch(steps)

several steps in one call; stops at the first failing step

save_recipe / run_recipe

save a finished task as label-based steps; replay with new values, step-checked

list_tabs, screenshot (fallback), stats

tabs; image for canvas apps; token/latency metrics

Generic skills run automatically: cookie banners / consent walls / newsletter popups are closed (preferring "Reject all"), custom dropdowns are opened and picked, secrets are never read.

Recipes & site memory live in ~/.page-map/recipes.json (never in the agent's context). Replay with zero model tokens: node scripts/recipe.js run signup-form --"Full name"="Alan Turing".

Parallel agents: every MCP server gets its own socket in ~/.page-map/sessions/; the native host routes replies to the session that asked, and each session sticks to its own tab.

Refs carry a random 4-letter prefix per page load (kqxa), so a ref from a previous page is rejected rather than clicking something else. Example read_page output:

Fixture Shop — http://127.0.0.1:5173/shop.html
kqxa3 link "Home"
kqxa4 link "Second page"
kqxa8 textbox "Search products" ="knives"
kqxa9 button "Search"
kqxa11 combobox "Country" ="Germany"
kqxa13 password "Password" ="<secret>" [secret]
… 1 more off-screen (scroll or viewport_only=false)

Benchmark (npm run bench)

Estimated tokens (chars/4) on real pages, 1280×800, vs. one screenshot ≈ 1,365 tokens:

page

find

outline

viewport

full page

raw HTML

GitHub repo page

38

363

1,024

2,921

116,339

Hacker News

0*

23

975

1,466

8,505

Amazon home

63

217

795

2,040

337,773

YouTube home

38

54

276

277

300,893

*no "search" element on HN. All views computed in < 15 ms. The real saving comes from find + outline + diffs replacing a screenshot on every step.

Head-to-head vs. screenshots (node scripts/compare.js --runs 3 --parallel)

Same 5 real tasks (GitHub, Hacker News, Wikipedia search, MDN, a signup form), same Chrome, Claude via claude -p, 3 runs each. "Screenshots" = classic screenshot + pixel-click loop. Answers checked automatically against live sources.

Page-Map (structure)

Screenshots

Success

15/15

12/15 (fails native dropdowns)

Cost

$0.40

$1.27 (3.2×)

Time

132 s

246 s (1.9×)

Turns

45

157

All 5 tasks in parallel

13.4 s wall

not possible (needs the one visible tab)

Recipes (learn once, replay with new values):

learn

agent replay

scripts/recipe.js replay

Wikipedia search

$0.045 · 13 s

$0.033 · 11.5 s

$0 · 0.8 s

Signup form

$0.026 · 11 s

$0.022 · 9 s

$0 · 3 s

Safety

  • Password, card/CSC, one-time-code, PIN, API-key/token field values — and any Luhn-valid card number — are never read (<secret>); type refuses secret fields unless allow_secret=true.

  • Blocklist (email, messaging, payments, banks, password managers by default; plain patterns cover subdomains) — checked in the service worker and against the page's real URL in the content script, so redirects can't slip through. Blocked tabs show only their host in list_tabs. Edit in the extension's Options page; agents can't change it.

  • Every result and every extension error is prefixed with a marker telling the agent that page text is untrusted data, not instructions.

  • Local only: unix socket ~/.page-map/pagemap.sock (0600 in a 0700 dir). No TCP port, no network calls.

Tests

npm test            # unit: DOM core (jsdom), native framing, MCP server with a fake extension
npm run test:e2e    # real Chromium + extension + native host + MCP server
npm run bench       # token benchmark on live sites

CHECKLIST.md lists every requirement and the test that proves it. .claude/agents/page-map-monitor.md is an independent auditor agent that re-checks the whole checklist.

Contributing

Issues, site reports and PRs are welcome — from people and from coding agents. See CONTRIBUTING.md and AGENTS.md. Security reports: SECURITY.md (please report privately).

Page-Map is an independent community project. It is not affiliated with or endorsed by Anthropic, Google, or any browser or AI vendor.

Limits / next

  • Main frame only (no iframes yet); closed shadow roots and canvas apps (Google Sheets, Figma) need screenshot.

  • One MCP server and one browser at a time: a second server or a second Chrome profile gets a clear refusal.

  • Any process running as your user could impersonate the server socket while no server runs — same trust level as your Chrome profile files.

  • The host wrapper pins the node binary path; re-run npm run install-host after upgrading node.

  • type(submit=true) skips form submit when the page preventDefaults Enter itself; pages that handle Enter without that may submit twice.

  • Huge pages (>60k nodes): only read_page says the scan was cut short.

  • Default blocklist is host-based, so icloud.com and wise.com are blocked whole (incl. non-sensitive parts). Card-number masking also hides IMEIs (also Luhn-valid).

  • Next: recipes (record/replay per-site action sequences = 0 tokens), image semantics (dominant color, OCR, CLIP), Chrome built-in AI labeling.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents and developers to automate real Chrome/Chromium browsers through the Chrome DevTools Protocol, with token-efficient snapshots, multi-action batching, shadow DOM traversal, system-page control, extension management, and network/WebSocket inspection.
      81
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to browse and interact with web pages through a token-efficient, structured page representation — orientation summaries, targeted element queries, and full detail only on request — instead of raw accessibility-tree dumps. Supports navigation, interaction, forms, screenshots, console and network monitoring, session/tab management, and browser-based development auditing.
      4 npm
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to browse and interact with web pages through structured, token-efficient representations instead of full accessibility-tree dumps, returning compact page orientations, targeted element queries, and detail on demand. Agents can navigate, click, type, fill forms, manage tabs and sessions, and inspect console or network activity at a fraction of the usual context cost.
      4 npm
      MIT