pagouse

Per Referenz, nicht per Pixel. pagouse ist ein Seiten-Agent für Coding-Agenten: eine Chromium-Erweiterung im täglichen Profil, die den Accessibility-Baum liest, deinem Agenten stabile ref_N-Labels übergibt und — nur mit einer Genehmigung — diese Knoten anklickt, ausfüllt und navigiert.

Standardmäßig beobachtet es nur. Mutationen erfordern --allow-input. Der optionale MCP-Server ist rein beobachtend und lässt sich nicht zum Tippen überreden.

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

So funktioniert es

• Die MV3-Erweiterung erstellt den Accessibility-Baum innerhalb der Seite, wo die Referenzen über separate CLI-Aufrufe hinweg gültig bleiben.

• Native Messaging startet pagoused, einen lokalen Daemon auf einem nur für den Besitzer zugänglichen Unix-Socket. Kein Remote-Debugging-Port, kein chrome.debugger.

• Ein Python-Kern ohne Abhängigkeiten verpackt alles in einer versionierten --json-Hülle (schema: 1).

Die Ebenen und die Nicht-Ziele: docs/architecture.md.

Related MCP server: Playwright MCP

Voraussetzungen

• Linux

• Python 3.13+ und uv

• Ein Chromium-basierter Browser (Chrome, Chromium, Brave, Edge) im täglichen Profil

Der Kern selbst hat null Abhängigkeiten. magick ist optional für die --fit-Verkleinerung.

Installation

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

install.sh installiert pagouse als uv-Tool, schreibt ~/.config/pagouse/config.toml, falls es fehlt, verlinkt die Agenten-Fähigkeit in jedes vorhandene Skill-Root und registriert den Native-Messaging-Host. Es ist idempotent. Details in docs/quickstart.md.

Lade dann extension/ entpackt (chrome://extensions → Entwicklermodus). pagouse --json doctor sollte ready melden, sobald das Popup grün ist.

Verwendung

Beobachten — benötigt nie eine Genehmigung:

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

Steuern — füge --allow-input hinzu, klicke per ref, niemals per Koordinaten:

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

Jeder Befehl und jede Flagge: docs/cli-reference.md. Die Hülle und Fehlercodes: docs/json-contract.md.

MCP-Zusatz und Agenten-Fähigkeit

uv tool install 'pagouse[mcp]' stellt pagouse-mcp bereit: nur schreibgeschützte Beobachtungswerkzeuge (doctor, tabs, snapshot, shot, wait, wait_ref). Es gibt kein Mutationswerkzeug; steuere die Seite über die CLI und eine Genehmigung.

install.sh verlinkt außerdem skills/pagouse/SKILL.md in jedes vorhandene Agenten-Skill-Root, sodass deine Agenten das Playbook ohne Einrichtung erhalten.

Sicherheit

Beobachtung fragt nie um Erlaubnis; Mutation verweigert ohne explizite Genehmigung. Schema-Deny, Origin-Policy und Geheimnis-Schwärzung werden im Kern durchgesetzt. Tab-Titel, URLs, Baumtext und Screenshot-Pixel sind nicht vertrauenswürdige Eingaben. Lies docs/security-model.md, bevor du Eingaben aktivierst. Melde Schwachstellen gemäß SECURITY.md.

Dokumentation

Lizenz

MIT. Siehe LICENSE.