---
type: reference
title: Pi Browser Use
description: Browser automation extension wrapping chrome-devtools-mcp with a browser_ prefix for pi-coding-agent.
resource: https://github.com/TGYD-helige/pi
tags:
  - pi
  - package
  - browser
  - chrome-devtools-mcp
  - unverified
timestamp: 2026-08-28
---
[pi-browser-use](https://github.com/TGYD-helige/pi) is a pi-coding-agent extension that wraps [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp), exposing all browser automation tools with a unified `browser_` prefix.

**License:** Apache-2.0

---

## Features

- **Dynamic tool discovery** — auto-proxies all upstream chrome-devtools-mcp tools with `browser_` prefix
- **Tool description augmentation** — adds usage hints for key tools
- **Result post-processing** — strips embedded snapshots, detects overlay/stale element issues
- **Optional visual analysis** — `browser_analyze_screenshot` via configurable vision model
- **Standalone mode** — runnable as independent MCP server via CLI

### Requirements

Node.js >= 20, Chrome (stable or newer), `@earendil-works/pi-coding-agent >= 0.74.0`.

---

## Installation

```bash
pi install npm:@amaster.ai/pi-browser-use
```

---

## Usage

### As pi-coding-agent Extension (Recommended)

Auto-discovers and loads on `session_start`. Configure in `.pi/settings.json`:

```json
{
  "pi-browser-use": {
    "headless": true,
    "channel": "stable",
    "viewport": "1280x720",
    "experimentalVision": true
  }
}
```

### As Standalone MCP Server

```bash
npx @amaster.ai/pi-browser-use --headless --viewport=1280x720
```

---

## Configuration

### Session Mode

| Mode | Description |
|------|-------------|
| `persistent` (default) | Reuses shared profile at `~/.pi/browser-profile` |
| `isolated` | Fresh ephemeral profile each session |
| `existing` | Connects to running browser instance |

### Browser Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `headless` | `boolean` | `false` | Run headless |
| `channel` | `string` | — | Chrome channel: `canary`, `dev`, `beta`, `stable` |
| `viewport` | `string` | — | Viewport size, for example `1280x720` |
| `userDataDir` | `string` | — | Custom user data directory |

### Vision Model

```json
{
  "pi-browser-use": {
    "visionModel": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}
```

Resolves API key and base URL from the model registry automatically.

---

## Key Tools

| Tool | Hint |
|------|------|
| `browser_click` | Use element uid from snapshot; UIDs invalidated after action |
| `browser_fill` | Does not work on canvas/custom widgets |
| `browser_press_key` | Accepts single key name only |
| `browser_take_snapshot` | Call first to get uids, and after every state-changing action |

---

## Cross-References

- See [Npx Skills](../skills/npx-skills.md) for the pi-package distribution system.
- See [OKF Specification](../references/okf-spec.md) for the knowledge bundle format.