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, nochrome.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
| Page | For |
|---|---|
| docs/quickstart.md | Install, load the extension, first commands |
| docs/cli-reference.md | Every command and flag, and the MCP surface |
| docs/json-contract.md | The --json envelope, per-action keys, error codes. Authoritative |
| docs/configuration.md | config.toml keys and every environment variable |
| docs/architecture.md | What problem this solves, the layers, the non-goals |
| docs/security-model.md | The page grant, scheme deny, untrusted data |
License
MIT. See LICENSE.
