pagouse

pagouse

Coding agents should not click web pages by pixel. pagouse is a pageagent: a Chromium extension on the daily profile that returns anaccessibility tree with ref_N labels, and (with a grant) clicks, fills,and navigates those nodes.

It observes by default. Mutation needs --allow-input. The optional MCPserver is observe-only and cannot be talked into typing.

$ pagouse --json snapshot --tab 1840 | jq -r '.snapshot.tree' | head
RootWebArea "Inbox" [ref_1]
  textbox "Search" [ref_2]
  button "Compose" [ref_3]

How it works

• The MV3 extension builds the accessibility tree inside the page, wherethe refs stay valid across separate CLI invocations.
• Native messaging starts pagoused, a local daemon on an owner-only unixsocket. No remote-debugging port, no chrome.debugger.
• A zero-dependency Python core wraps it all in a versioned --jsonenvelope (schema: 1).

The layers and the non-goals: docs/architecture.md.

Requirements

• Linux
• Python 3.13+ and uv
• A Chromium-family browser (Chrome, Chromium, Brave, Edge) on the dailyprofile

The core itself has zero dependencies. magick is optional for --fitdownscaling.

Install

git clone https://github.com/gianlucamazza/pagouse
cd pagouse
./install.sh

install.sh installs pagouse as a uv tool, writes~/.config/pagouse/config.toml if missing, links the agent skill into anyexisting skill root, and registers the native-messaging host. It isidempotent. Details in docs/quickstart.md.

Then load extension/ unpacked (chrome://extensions → Developer mode).pagouse --json doctor should report ready once the popup is green.

Usage

Observe — never needs a grant:

pagouse --json tabs
pagouse --json snapshot --tab ID

Drive — add --allow-input, click by ref, never by coordinates:

pagouse --json --allow-input click --ref ref_4 --tab ID --then snapshot

Every command and flag: docs/cli-reference.md. Theenvelope and error codes: docs/json-contract.md.

MCP extra and agent skill

uv tool install 'pagouse[mcp]' provides pagouse-mcp: read-onlyobservation tools only. There is no mutate tool; drive the page through theCLI and a grant.

install.sh also links skills/pagouse/SKILL.md into any existing agentskill root, so your agents get the playbook without setup.

Security

Observation never asks permission; mutation refuses without an explicitgrant. Scheme deny, origin policy, and secret redaction are enforced in thecore. Tab titles, URLs, tree text, and shot pixels are untrusted input.Read docs/security-model.md before enablinginput. Report vulnerabilities per SECURITY.md.

Documentation

License

MIT. See LICENSE.