A headless-first browser for AI agents.

CatPaw is not a Chromium wrapper, and not a rendering engine with an automation API added on. Its first user is an agent. It runs JavaScript and the DOM faithfully, computes layout only when something asks for geometry, and answers the questions an agent has: what is on the page, what changed, and whether the page is done.

• Compact snapshots, stable refs

  snapshot returns a CatPaw Snapshot Text tree, a superset of Playwright's aria snapshot. Elements are named by refs such as e12 that stay valid until the element leaves the page and are never reused. A whole snapshot is capped at 4000 tokens; the rest is folded for the agent to open.

• Diffs after actions

  An action answers once the page has settled, with what happened and what changed, so one agent step is one round trip. A new document comes back whole.

• Settledness

  CatPaw knows every pending fetch, timer, animation frame and microtask. A page that does not settle is reported with its causes, down to the script position that started them. Time a page spends only on timers passes at once.

• Confirmations before side effects

  Under the default policy, a form submission or an upload waits for the user. A host that supports MCP elicitation asks there; otherwise CatPaw opens an approval page in the user's own browser. The agent never sees the key.

• Hand-off to the user

  When a site needs a person, such as a login or a check meant for humans, handoff opens the tab in the user's own browser. They click, type and scroll as on the page itself, and the agent gets the page back with what they typed masked.

• Flight recorder

  --flight-log keeps a journal of every call, confirmation and decision, with a screenshot per action if you ask for one. Typed passwords are kept as their length.

• Record and replay

  --record-har keeps a session's traffic and --replay-har serves it back with no network. With a fixed seed and clock, a replay gives the same results byte for byte.

• Honest identity

  CatPaw says what it is, signs requests with Web Bot Auth when you give it a key, and ships no fingerprint impersonation and no CAPTCHA solvers. Loopback and private addresses are refused unless you allow them. For site owners.

ok click e16 button "Add to cart"
# s4 diff-from=s3 tab=t1 doc=d1 url=(same) scroll=0,0 settled=yes changed=1 added=1 removed=1 unchanged=27
~ e11 button "Cart, empty" → "Cart, 1 items"
+ e37 button "Remove" (in e13, after e15)
- e16 button "Add to cart"

Twenty tasks on sites made for automation practice live in the repository, each with its recorded traffic and the transcript an agent sees. The table sets the bytes of every tool result an agent receives against Playwright MCP taking the same steps.

How this was measured: bytes are all the tool results an agent receives over a task. CatPaw's numbers come from the recordings. Playwright MCP is @playwright/mcp 0.0.83 with headless Chrome, taking the same steps live on 2026-10-08, the median of three runs. Playwright MCP keeps the page snapshot in a file and links it from a result when the page changed; an agent reads it to see the page and find its next target, so the file counts too, as one more call. CatPaw's numbers include the calls that wait for the user's approval, which Playwright MCP does not make. The task in which the user declines has no counterpart there, so the totals leave it out. The content-site rows were measured the same way on the same day; those recordings stay out of the repository. The per-task table and the commands that regenerate it are in the README.

Version 0.1 is a preview. The first four milestones are done: fetch and read, scripts, interaction, and the agent API. Expect gaps, and expect some sites not to work.

Next on the roadmap: challenge detection and measured pass rates, then multi-tenant limits, OpenTelemetry, Docker, a CDP subset for Puppeteer and an optional V8 backend. The full list of known gaps is in the architecture notes.