pagouse

참조(ref)로, 픽셀이 아닌. pagouse는 코딩 에이전트를 위한 페이지 에이전트입니다. 일상 프로필에서 실행되는 Chromium 확장 프로그램으로, 접근성 트리를 읽고 에이전트에게 안정적인 ref_N 라벨을 전달하며, 승인(grant)이 있을 때만 해당 노드를 클릭하고, 채우고, 탐색합니다.

기본적으로 관찰만 합니다. 변경(mutation)에는 --allow-input이 필요합니다. 선택적 MCP 서버는 관찰 전용이며 입력을 강제할 수 없습니다.

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

작동 방식

• MV3 확장 프로그램은 페이지 내부에서 접근성 트리를 구축하므로, 별도의 CLI 호출 간에도 참조가 유효하게 유지됩니다.

• 네이티브 메시징은 소유자 전용 유닉스 소켓에서 로컬 데몬인 pagoused를 시작합니다. 원격 디버깅 포트도, chrome.debugger도 없습니다.

• 의존성이 없는 Python 코어가 이를 모두 버전이 있는 --json 봉투(schema: 1)로 감쌉니다.

계층 구조와 비목표(non-goals): docs/architecture.md.

Related MCP server: Playwright MCP

요구 사항

• Linux

• Python 3.13+ 및 uv

• 일일 프로필에서 실행되는 Chromium 계열 브라우저(Chrome, Chromium, Brave, Edge)

코어 자체는 의존성이 전혀 없습니다. magick은 --fit 다운스케일링에만 선택적으로 필요합니다.

설치

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

install.sh는 pagouse를 uv 도구로 설치하고, ~/.config/pagouse/config.toml이 없으면 작성하며, 에이전트 스킬을 기존 스킬 루트에 연결하고, 네이티브 메시징 호스트를 등록합니다. 멱등적입니다. 자세한 내용은 docs/quickstart.md를 참조하세요.

그런 다음 extension/을 압축 해제 상태로 로드합니다(chrome://extensions → 개발자 모드). 팝업이 초록색이 되면 pagouse --json doctor가 ready를 보고해야 합니다.

사용법

관찰 — 승인이 절대 필요 없음:

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

구동 — --allow-input을 추가하고, 좌표가 아닌 ref로 클릭합니다:

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

모든 명령과 플래그: docs/cli-reference.md. 봉투 및 오류 코드: docs/json-contract.md.

MCP 확장 및 에이전트 스킬

uv tool install 'pagouse[mcp]'는 pagouse-mcp를 제공합니다: 읽기 전용 관찰 도구만 제공합니다(doctor, tabs, snapshot, shot, wait, wait_ref). 변경 도구는 없습니다. CLI와 승인을 통해 페이지를 구동하세요.

install.sh는 또한 skills/pagouse/SKILL.md를 기존 에이전트 스킬 루트에 연결하므로, 에이전트가 별도 설정 없이 플레이북을 얻을 수 있습니다.

보안

관찰은 승인을 요청하지 않습니다. 변경은 명시적 승인 없이 거부됩니다. 스킴 거부, 출처 정책, 비밀 정보 삭제는 코어에서 강제됩니다. 탭 제목, URL, 트리 텍스트, 스크린샷 픽셀은 신뢰할 수 없는 입력입니다. 입력을 활성화하기 전에 docs/security-model.md를 읽으세요. 취약점은 SECURITY.md에 따라 보고하세요.

문서

라이선스

MIT. LICENSE 참조.# pagouse

픽셀이 아닌 참조로. pagouse는 코딩 에이전트를 위한 페이지 에이전트입니다. 일일 프로필에서 실행되는 Chromium 확장 프로그램으로, 접근성 트리를 읽고 에이전트에게 안정적인 ref_N 라벨을 전달하며, 승인(grant)이 있을 때만 해당 노드를 클릭하고, 채우고, 탐색합니다.

기본적으로 관찰만 합니다. 변경(mutation)에는 --allow-input이 필요합니다. 선택적 MCP 서버는 관찰 전용이며 입력을 강제할 수 없습니다.

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

작동 방식

• MV3 확장 프로그램은 페이지 내부에서 접근성 트리를 구축하므로, 별도의 CLI 호출 간에도 참조가 유효하게 유지됩니다.

• 네이티브 메시징은 소유자 전용 유닉스 소켓에서 로컬 데몬인 pagoused를 시작합니다. 원격 디버깅 포트도, chrome.debugger도 없습니다.

• 의존성이 없는 Python 코어가 이를 모두 버전이 있는 --json 봉투(schema: 1)로 감쌉니다.

계층 구조와 비목표(non-goals): docs/architecture.md.

요구 사항

• Linux

• Python 3.13+ 및 uv

• 일일 프로필에서 실행되는 Chromium 계열 브라우저(Chrome, Chromium, Brave, Edge)

코어 자체는 의존성이 전혀 없습니다. magick은 --fit 다운스케일링에만 선택적으로 필요합니다.

설치

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

install.sh는 pagouse를 uv 도구로 설치하고, ~/.config/pagouse/config.toml이 없으면 작성하며, 에이전트 스킬을 기존 스킬 루트에 연결하고, 네이티브 메시징 호스트를 등록합니다. 멱등적입니다. 자세한 내용은 docs/quickstart.md를 참조하세요.

그런 다음 extension/을 압축 해제 상태로 로드합니다(chrome://extensions → 개발자 모드). 팝업이 초록색이 되면 pagouse --json doctor가 ready를 보고해야 합니다.

사용법

관찰 — 승인가 절대 필요 없습니다:

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

구동 — --allow-input을 추가하고, 좌표가 아닌 ref로 클릭합니다:

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

모든 명령과 플래그: docs/cli-reference.md. 봉투 및 오류 코드: docs/json-contract.md.

MCP 확장 및 에이전트 스킬

uv tool install 'pagouse[mcp]'는 pagouse-mcp를 제공합니다: 읽기 전용 관찰 도구만 제공합니다(doctor, tabs, snapshot, shot, wait, wait_ref). 변경 도구는 없습니다. CLI와 승인를 통해 페이지를 구동하세요.

install.sh는 또한 skills/pagouse/SKILL.md를 기존 에이전트 스킬 루트에 연결하므로, 에이전트가 별도 설정 없이 플레이북을 얻을 수 있습니다.

보안

관찰은 승인를 요청하지 않습니다. 변경은 명시적 승인 없이 거부됩니다. 스킴 거부, 출처 정책, 비밀 정보 삭제는 코어에서 강제됩니다. 탭 제목, URL, 트리 텍스트, 스크린샷 픽셀은 신뢰할 수 없는 입력입니다. 입력을 활성화하기 전에 docs/security-model.md를 읽으세요. 취약점은 SECURITY.md에 따라 보고하세요.

문서

라이선스

MIT. LICENSE를 참조하세요.