# pi-agent-browser-native

> pi extension that exposes agent-browser as a native tool for browser automation

Latest version **0.9.41** (published 2026-11-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install pi-agent-browser-native
pnpm add pi-agent-browser-native
yarn add pi-agent-browser-native
bun add pi-agent-browser-native
```

Provides the commands `pi-agent-browser-config`, `pi-agent-browser-doctor`, `pi-agent-browser-convert`.

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.41 |
| Published | 2026-11-20 |
| First published | 2026-04-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | ^24.22.3 \|\| >=26.13.1 |
| Dependencies | 7 |
| Unpacked size | 3.8 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 248 |
| Author | Mitch Fultz |
| Maintainers | fitchmultz |
| Keywords | pi-package, pi, pi-extension, extension, agent-browser, browser-automation, typescript, npm-package |

## Links

- npm: https://www.npmjs.com/package/pi-agent-browser-native
- Repository: https://github.com/fitchmultz/pi-agent-browser-native
- Homepage: https://github.com/fitchmultz/pi-agent-browser-native#readme
- Issues: https://github.com/fitchmultz/pi-agent-browser-native/issues
- npm.io page: https://npm.io/package/pi-agent-browser-native

## Dependencies (7)

- [which](https://npm.io/package/which.md) 2.0.2
- [semver](https://npm.io/package/semver.md) 7.8.6
- [path-key](https://npm.io/package/path-key.md) 3.1.1
- [cross-spawn](https://npm.io/package/cross-spawn.md) 7.0.6
- [stream-json](https://npm.io/package/stream-json.md) 3.7.0
- [stream-chain](https://npm.io/package/stream-chain.md) 4.2.6
- [strip-json-comments](https://npm.io/package/strip-json-comments.md) 5.0.3

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.9.41 (latest) — 2026-11-20
- 0.9.40 — 2026-11-20
- 0.9.39 — 2026-11-20
- 0.9.38 — 2026-11-18
- 0.9.37 — 2026-11-18
- 0.9.36 — 2026-11-18
- 0.9.35 — 2026-11-17
- 0.9.34 — 2026-11-17
- 0.9.33 — 2026-11-17
- 0.9.32 — 2026-11-14
- 0.9.31 — 2026-11-14
- 0.9.30 — 2026-11-14
- 0.9.29 — 2026-11-14
- 0.9.28 — 2026-11-13
- 0.9.26 — 2026-11-13
- … 129 more at https://npm.io/package/pi-agent-browser-native/versions

## README

# pi-agent-browser-native

pi-agent-browser-native adds browser tools to [Pi](https://pi.dev). Use it to read pages, test web apps, and save screenshots through [agent-browser](https://agent-browser.dev/).

![A prompt in Pi becomes a native browser tool call. The separately installed agent-browser CLI controls a browser and returns page observations and file artifacts.](.github/readme/browser-flow.png)

## Install and start

Use supported Node.js and Pi releases. This extension requires a separate agent-browser installation. See the [runtime requirements](docs/REQUIREMENTS.md#runtime-requirements) for minimum versions.

The latest stable agent-browser release is recommended. Older stable releases are supported down to the [documented minimum](docs/REQUIREMENTS.md#runtime-requirements), with no upper version cap. See the [command guide](docs/COMMAND_REFERENCE.md) for native download fixes, daemon-file cleanup, indexed batch output, and the current MCP limitation.

```bash
npm install -g agent-browser --allow-scripts=agent-browser
agent-browser install
pi install npm:pi-agent-browser-native
pi
```

The npm flag permits the browser CLI's install script. `agent-browser install` downloads Chrome for Testing. On Linux, use `agent-browser install --with-deps` if browser libraries are missing. Android users need the [Termux setup](docs/REFERENCE.md#android--termux).

Ask Pi:

```text
Open https://example.com with agent_browser.
Take an interactive snapshot.
Save a screenshot to /tmp/example.png.
Close the browser when finished.
```

After a package update, quit Pi fully. Start Pi again to load the new tools. `/reload` can retain the previous compiled code.

Existing browser-bearing conversations resume automatically at their original journal path, without rewriting history or running a converter. See [session storage](docs/SESSION_STORAGE.md#resuming-a-retained-legacy-journal) for replay and recovery limits.

If shutdown cleanup fails, Pi warns with the exact browser session or Electron launch to retry. Resume the same conversation with this extension to retry unfinished cleanup automatically, including off-branch resources. Partial Electron profiles remain protected. See [cleanup recovery](docs/SESSION_STORAGE.md#shutdown-cleanup-recovery).

Read the [command reference](docs/COMMAND_REFERENCE.md) for your next browser task.

## Browser tools

Describe the task in your conversation. Pi can click controls, fill forms, check text and URLs, and save files.

| Tool                       | Use                                                 |
| -------------------------- | --------------------------------------------------- |
| `agent_browser`            | Browser commands and fixed `batch --bail` sequences |
| `agent_browser_web_search` | Optional Exa or Brave search through provider APIs  |

For loops, branches, or aggregation, enable Pi's `codemode` tool (for example, `--tools +codemode`). Its scripts call `tools.agent_browser()` against the same browser.

Action, QA, Electron, source, and network-source tools are deferred: Pi's native `tool_search` loads them when a task needs them, and codemode scripts can call them directly. Like Pi's own MCP extension, the browser extension activates a registered `tool_search` at session start and after tree navigation, unless the branch recorded removing it. When neither `tool_search` nor codemode is active, specialized tools that are not selected directly cannot be called. The extension checks as each run starts, after every extension's session start handling, and warns once.

For example, Pi opens and inspects a page with these calls:

```json
{ "args": ["open", "https://example.com"] }
{ "args": ["snapshot", "-i"] }
```

Snapshots give Pi current `@eN` references for controls. The recommended agent-browser 0.43.0 adds DOM hints for unnamed or duplicate-name controls; use their refs, since hints are not accessible names. Refresh the snapshot after navigation or page changes. Check the resulting page after a click; command success alone does not prove the app changed.

Browser windows are headless by default: pass `--headed` in `args` to show the window. There is no `--headless` flag; upstream rejects it as an unknown command.

Tab management uses singular `tab` (`tab list`, `tab new [url]`, `tab <id>`, `tab close [id]`). If a call uses plural `tabs`, the error result explains the `tab` commands and includes a read-only `use-tab-list` recovery action when listing tabs.

For a trial without a saved package setting, run:

```bash
pi --no-extensions -e builtin:tool-search -e npm:pi-agent-browser-native
```

This command loads this extension explicitly and disables automatic extension loading, including Pi's built-in `tool_search`; `-e builtin:tool-search` loads it again so the deferred tools stay reachable. Other Pi settings and resource types still apply.

## Profiles and privacy

Ordinary calls use one named browser per root Pi session. A parent and its subagents share that browser. Separate roots get separate browser names.

Shared root browsers survive Pi exit. Ask Pi to close your group's browser when finished.

A `sessionMode: "fresh"` batch that ends by closing its browser leaves any prior managed browser current, including its namespace and launch settings. Without a prior browser, no managed browser is current. Check `details.managedSessionOutcome.activeAfter` and `currentSessionName` rather than treating a successful batch as an active browser.

Profile access exposes private page content to the model. That content can persist in transcripts and saved files. Use temporary profiles for tests.

Credential-like values, including CDP transport headers on the [pinned Android build](docs/REFERENCE.md#android--termux), are redacted, but ordinary page text stays visible. Verify the signed-in page after you select a profile or restore browser state.

Post-click overlay diagnostics keep their newer refs for follow-up actions, including when a semantic action used an earlier snapshot to find its target.

Screenshot captures reported at a different path replace the requested file, even when it already exists. If the reported capture is missing, the result fails verification and never attaches the old destination image.

Native `batch --omit-command` keeps indexed results without echoed commands. Cookie/storage redaction, ordered close/reopen effects, snapshot refs, and artifact verification still apply, including when empty stdin rows are skipped.

When a direct `read` saves its result to a file, follow the returned path and `contentPointer`. The document is at `/content` in the saved payload, even though inline text is at `data.content` in the tool result. See [reading saved results](docs/TOOL_CONTRACT.md#canonical-observation).

Ask for a headed browser if you need to watch a task or complete a login. Remote environments can keep the window off your desktop.

See [profiles and sessions](docs/REFERENCE.md#authenticatedprofile-workflows) for profile selection, restore limits, and cleanup.

## Optional search and settings

To enable web search, set `EXA_API_KEY` or `BRAVE_API_KEY` before you start Pi. Exa is the default when both keys work. Provider charges apply.

Set provider preferences and browser defaults in `~/.pi/config/pi-agent-browser-native/config.json`. Trusted projects can use `.pi/config/pi-agent-browser-native/config.json`. `PI_AGENT_BROWSER_CONFIG` selects an override file.

Malformed config files and search-provider JSON report errors without parser previews that could expose credentials, and search-provider HTTP failures report only the status with a fixed hint.

Read [configuration examples](docs/REFERENCE.md#optional-package-config-and-web-search) for secret references, provider selection, and profile defaults.

## Troubleshooting and limits

Run the read-only health check:

```bash
npm exec --package pi-agent-browser-native -- pi-agent-browser-doctor
```

It checks the Node.js running the doctor, the browser CLI, Pi version, and duplicate Pi package sources. Pi may use a different runtime or Node executable, so verify it separately. The doctor does not change settings.

For browser execution coordination failures, launch Pi with Node's standard `NODE_DEBUG=pi-agent-browser-policy` environment setting (PowerShell: `$env:NODE_DEBUG = 'pi-agent-browser-policy'`). This optional channel is silent by default and writes failure-stage breadcrumbs to stderr, not tool results. Lines carry Node's PID plus an opaque per-process attempt number and acquisition or release phase (cleanup has separate stage labels); standalone library inspections use attempt `0`. They contain fixed reasons and normalized native error codes/syscalls, never claim contents, paths, session names, or process-start identities. Normal choosing-state missing tickets and confirmed disappearing claims are quiet. A release/cleanup breadcrumb alone does not explain an acquisition failure. Unset `NODE_DEBUG` after collecting diagnostics; these observations do not change coordination policy or budgets.

This package is still early-stage; expect breaking changes as it evolves. Supported platforms are Apple Silicon macOS and Linux. Official/fork host/API qualification remains strict. Release tests do not cover Android. Electron desktop tools do not apply to Android apps. See the [support matrix](docs/SUPPORT_MATRIX.md) for details.

For recordings, install `ffmpeg` with the encoder for your WebM or MP4 output. Verify the completed file after you stop the recording.

Recent agent-browser releases support finite `mcp call` invocations, but this extension currently rejects every non-help `mcp` call. MCP session identity, cross-session coordination, credential presentation, and image handling are not integrated. Use the direct browser tools; see the [MCP boundary](docs/TOOL_CONTRACT.md#native-mcp-boundary).

For remote browsers, use a URL that the browser host can reach. `localhost` refers to the browser host.

Preparatory tab/page checks do not launch a stopped caller-owned explicit `--session` ahead of its launch-flagged command, including after resume. After dispatch, the old browser's tab identity and refs are retired. A successful command observes the replacement page before follow-ups; if it cannot be observed, the target stays unknown. Put launch flags on the launch command. On a running browser, `agent-browser` retains session launch settings across follow-ups and relaunches when a supplied launch setting changes or `--relaunch` is passed; after a relaunch the result warns that the prior page is gone and offers `reopen-page-after-browser-relaunch`. If a wedged tab triggers upstream's watchdog (`page_wedged:`), the result classifies as `page-wedged` and offers tab/reopen recovery.

After its own `eval` or `reload`, the tool checks the page itself. A result that starts with `Page URL changed during this call:` names the new page; one that starts with `Page not verified:` means page-content commands are refused until `get url` or a navigation.

For stale references or unexpected tabs, follow the returned recovery actions. Take a fresh snapshot before another interaction. An incomparable saved process identity after an update invalidates old refs without reloading a still-live page. A snapshot inside a batch does not protect refs used after a later page-changing step; add another snapshot after that step or split the batch.

## More documentation

- [Detailed reference](docs/REFERENCE.md): platform setup, browser examples, compatibility notes, and development checks.
- [Tool contract](docs/TOOL_CONTRACT.md): exact inputs, results, and image geometry.
- [Electron guide](docs/ELECTRON.md): desktop discovery, isolated launch, and cleanup.
- [Session storage](docs/SESSION_STORAGE.md): replay, large histories, and session conversion.
- [Architecture](docs/ARCHITECTURE.md): extension design.
- [Performance](docs/PERFORMANCE.md): measured baselines, improvements, and reproducible profiling.
- [Code quality](docs/CODE_QUALITY.md) and [release process](docs/RELEASE.md): maintainer procedures.

## License

[MIT](LICENSE). Copyright Mitch Fultz.

---
_Source: https://npm.io/package/pi-agent-browser-native · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
