pi-chrome

Agent-first Chrome tools for Pi. Complex browser intent stays in Chat; there is no /chrome command or authorization control plane. The cross-Session Web Surface is a browser-activity supervision console: it projects explicit running tool activity, bounded live events, recent evidence, and idle Session-owned tabs. It does not recreate navigation, click, fill, snapshot, or screenshot controls.

Install

pi install npm:@yansircc/pi-chrome

Download the package-provided browser-extension ZIP from Pipee, open chrome://extensions, enable Developer mode, and drag the ZIP directly onto the page. If the current Chrome build or enterprise policy rejects ZIP installation, extract it and use Load unpacked as the fallback. The popup is read-only. Once loaded, the extension connects to the local Pi bridge automatically.

Ask Pi to use Chrome normally. All 25 typed atomic tools and chrome_status are registered directly; the Extension never reads or rewrites Pi's active-tool selection.

chrome_status reports one of ready, waiting-for-extension, offline, or error, plus the extension directory when setup is incomplete. The Chrome popup stays read-only. Pipee combines that status with Session-owned activity, evidence, and idle-tab projections. Its only mutations are terminating the owning Session's current Chrome tool and closing one explicitly selected idle tab after confirmation; it never mirrors the DOM or falls back to Chrome's active tab.

Operation model

One operation descriptor map owns every atomic tool name, public schema, wire projection, result contract, and deadline. Tool registration and browser dispatch derive from that map; there are no aliases or generic command runners.

Start with chrome_snapshot, then use the returned Action Graph refs:

{ "mode": "interactive" }

{ "ref": "@el-12", "includeSnapshot": true }

Refs identify live DOM nodes. A stale ref requires another snapshot; role/name guessing is not a fallback. Explicit tab targets use one tagged selector:

{ "target": { "by": "id", "value": 42 }, "mode": "interactive" }

The other target forms are { "by": "url", "value": "github.com" } and { "by": "title", "value": "GitHub" }. The selector is resolved once at command entry.

Without an explicit target, page and input operations allocate a session-owned tab when none exists, use it when exactly one exists, and require an exact target when several exist. Session shutdown asks the browser to clean that session's owned targets.

Development

Requires Chrome 120 or newer and Node.js 22.19 or newer.

pnpm install --frozen-lockfile
pnpm verify
vp run smoke:connector

The package contains a self-contained Pi Extension bundle and the built browser extension. Candidate checks load the raw npm archive without installing package-local dependencies.

See Architecture, Examples, and FAQ.