pi-browser

npm · Pi package directory

Let a Pi coding agent inspect and interact with JavaScript-heavy pages through Patchright/Chromium, without driving your everyday browser profile. Prefer pi-web-access for static public HTML. This is not a CAPTCHA solver or a complete sandbox.

Also available as pi-browser-mcp, a standalone stdio MCP service. With the MCP gateway, cookie approvals go directly to the human and profiles/login/settings live in /gateway → Services → browser → Open app. No browser-specific Pi extension is needed. See MCP setup and migration; do not load both backends at once.

Install

Requires Node >=22.19.0 and Google Chrome or Chromium; development and CI test with Pi 0.85.1. Linux uses headed Xvfb when installed, otherwise headless mode.

pi install npm:@kvidzibo/pi-browser

For a local checkout, Pi does not install dependencies automatically:

cd /absolute/path/to/pi-browser
npm install --omit=dev --omit=peer
pi install /absolute/path/to/pi-browser

Load through packages only, not also extensions, then /reload or restart Pi. PI_BROWSER_EXECUTABLE overrides browser discovery. Run /browser doctor to check local prerequisites without launching a browser, contacting sites, or reading cookies. This README tracks repository source; npm releases and Git tags may lag.

Quick example

Start a fresh Pi session, or run /browser logout yourself for an anonymous profile. Then ask Pi:

Use browser to open https://example.com in an anonymous session.
Take a snapshot and report the page title and first heading.
Do not log in, submit forms or follow links. Close the browser when done.

This is a usage example, not a recorded session. It needs public network access. The browser tool handles navigation, snapshots, clicks, typing, tabs, and screenshots. browser action list_cookies lists cookie names, domains, paths, expiry and security flags available in Chromium's Linux Default profile after approval, never values. Omit origins for all domains or supply exact origins to filter. Listing does not import cookies or grant signed-in access; request_cookies needs separate approval. Use element references from the latest snapshot. For continuation, use the returned snapshotId and offset; navigating or switching tabs invalidates old references.

Signed-in work and safety

• Full system permissions, not a sandbox. Install only trusted code. Page text is untrusted; the agent can act as you on authorized sites.
• Browsing starts anonymous. /pi-browser creates named, private profiles whose cookies and site storage survive close/logout/reload/shutdown. Selecting one authorizes the agent to act as you on all public websites for this session, without origin prompts. Nothing is selected automatically; the model cannot create or select profiles. /browser login opens the selected profile for manual login. Profiles live under ~/.pi/agent/browser-profiles/<name>/user-data (or PI_CODING_AGENT_DIR); close all users before manually deleting a profile directory. Use each profile in only one Pi process at a time.
• The model can request browser action request_cookies for exact origins and optional cookie names; only you can approve. Linux Chromium's Default profile is supported, not Firefox. Your everyday profile is never driven.
• Matching/subset cookie requests reuse the approved scope without prompting or reimporting. Subsets do not narrow access. Broader requests require approval, replace the old grants/profile, and close its tabs; denial leaves access unchanged.
• /browser logout, /reload, session changes, and shutdown revoke grants. /browser close does not. Use logout before narrowing access, or the manual import command to refresh cookies. Imports are snapshots; some logins will not transfer.
• Never put passwords in the tool. The model cannot approve itself, open manual login, or switch to your real display. Do not retry denied access without direction. Cookie approval requires interactive TUI/RPC dialogs; print/JSON mode fails closed.
• Localhost, private addresses, and file: URLs stay blocked, including for saved profiles. Scoped login/import grants still restrict document destinations to exact origins; other public hosts may supply cookieless subresources. These controls are not a guarantee against every network risk.
• Screenshots are unredacted and their files survive close/logout. Tool text redacts cookie values of 6+ characters and sensitive URL query keys, but is not a complete secret scanner. Delete retained screenshots when no longer needed. Cancellation cannot undo actions already dispatched to a site.

Chromium uses native window sizing without user-agent spoofing. /pi-browser doctor reports compatibility limits, including cookieless third-party routing and blocked service workers. These changes do not guarantee CAPTCHA acceptance.

Validation

From the repository root:

npm ci --include=dev --ignore-scripts
npm run typecheck
npm run test:mcp
xvfb-run -a npm test
xvfb-run -a npm run test:integration

The default suite uses fixtures and offline Pi checks, not a live browser. Integration tests launch isolated Chromium with synthetic cookies and loopback fixtures, never your real profile or public sites. Public-network smoke is opt-in.

Detailed guides

In the source repository: installation, snapshots, login and troubleshooting, security and network internals, and development, integration prerequisites and architecture. The npm package includes this quickstart; the detailed guides live in the checkout.

MIT.