pagouse

Por ref, no por píxel. pagouse es un agente de página para agentes de codificación: una extensión de Chromium en el perfil diario que lee el árbol de accesibilidad, entrega a tu agente etiquetas estables ref_N y — solo con un permiso — hace clic, rellena y navega por esos nodos.

Observa por defecto. La mutación requiere --allow-input. El servidor MCP opcional es solo de observación y no se le puede convencer para que escriba.

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

Cómo funciona

• La extensión MV3 construye el árbol de accesibilidad dentro de la página, donde los refs siguen siendo válidos entre invocaciones separadas de la CLI.

• La mensajería nativa inicia pagoused, un demonio local en un socket unix de solo propietario. Sin puerto de depuración remota, sin chrome.debugger.

• Un núcleo Python de cero dependencias lo envuelve todo en un sobre --json versionado (schema: 1).

Las capas y los no objetivos: docs/architecture.md.

Related MCP server: Playwright MCP

Requisitos

• Linux

• Python 3.13+ y uv

• Un navegador de la familia Chromium (Chrome, Chromium, Brave, Edge) en el perfil diario

El núcleo en sí tiene cero dependencias. magick es opcional para el redimensionado --fit.

Instalación

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

install.sh instala pagouse como una herramienta uv, escribe ~/.config/pagouse/config.toml si falta, enlaza la habilidad del agente en cualquier raíz de habilidades existente y registra el host de mensajería nativa. Es idempotente. Detalles en docs/quickstart.md.

Luego carga extension/ sin empaquetar (chrome://extensions → Modo de desarrollador). pagouse --json doctor debería informar ready una vez que el popup esté en verde.

Uso

Observa — nunca necesita un permiso:

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

Conduce — añade --allow-input, haz clic por ref, nunca por coordenadas:

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

Todos los comandos y banderas: docs/cli-reference.md. El sobre y los códigos de error: docs/json-contract.md.

Extra MCP y habilidad del agente

uv tool install 'pagouse[mcp]' proporciona pagouse-mcp: solo herramientas de observación de solo lectura (doctor, tabs, snapshot, shot, wait, wait_ref). No hay herramienta de mutación; conduce la página mediante la CLI y un permiso.

install.sh también enlaza skills/pagouse/SKILL.md en cualquier raíz de habilidades de agente existente, para que tus agentes obtengan el manual sin configuración.

Seguridad

La observación nunca pide permiso; la mutación se niega sin un permiso explícito. La denegación de esquemas, la política de origen y el enmascaramiento de secretos se aplican en el núcleo. Los títulos de pestañas, las URL, el texto del árbol y los píxeles de las capturas son entrada no fiable. Lee docs/security-model.md antes de habilitar la entrada. Reporta vulnerabilidades según SECURITY.md.

Documentación

Licencia

MIT. Ver LICENSE.