pi-claude-chrome-extension

A pi extension that bridges the Claude Chrome extension to pi, exposing full browser automation tools (click, type, screenshot, JS execution, network inspection, GIF recording, and more) directly to the LLM.

How it works

pi (LLM) ──► bridge (IPC / TCP) ──► native-host.cjs ──► Claude Chrome extension ──► browser

The extension registers a native messaging host so the Claude Chrome extension can forward tool calls from pi into the real browser — no Playwright, no Puppeteer, just the extension you already have installed.

Connection modes

| Environment | Transport | |-------------|-----------| | Windows (native) | Named pipe \\.\pipe\pi-chrome-bridge-<user> | | macOS / Linux | Unix socket /tmp/pi-chrome-bridge-<user>.sock | | WSL (default) | TCP 127.0.0.1:47777 → Windows Chrome | | WSL + wslLinuxMode: true | Unix socket (for Chrome-inside-WSL setups) |

The native host always listens on both the platform IPC channel and the TCP port, so WSL and native clients can coexist.

Requirements

• pi coding agent
• Claude Chrome extension installed and logged in
• Google Chrome (or Brave / Edge / Vivaldi)
• Node.js ≥ 18

Installation

Install the extension into pi with a single command:

pi install npm:oira666_pi-claude-chrome-extension

After installing, restart Chrome once so it picks up the newly registered native host, then open any page. The extension will connect automatically.

Verify the connection

Inside a pi session run:

/chrome-status

You should see 🌐 Chrome: connected.

Troubleshoot

/chrome-install     — force-reinstall the native host + show registry diagnostics
/chrome-debug       — show the bat-level debug log (Windows/WSL startup errors)
/chrome-reconnect   — step-by-step reconnect guide

WSL support

When pi runs inside WSL and Chrome runs on Windows (the common setup), the bridge automatically:

1. Installs on the Windows side — copies native-host.cjs to C:\Users\<user>\AppData\Local\pi-chrome-bridge\, writes the .bat launcher, and registers the Windows registry keys, all via cmd.exe.
2. Connects via TCP loopback — bridge.ts connects to 127.0.0.1:47777 instead of a Unix socket, reaching the native host that Chrome spawned on Windows.

No extra setup needed — just run /chrome-install once from inside WSL and restart Chrome.

WSL with Chrome inside WSL

If you run Chrome inside WSL itself (unusual), add this to ~/.pi/settings.json:

{
  "chrome-bridge": {
    "wslLinuxMode": true
  }
}

This switches back to the Unix socket transport.

Configuration

All options go in ~/.pi/agent/settings.json (the global pi settings file) under the "chrome-bridge" key:

{
  "chrome-bridge": {
    "port": 47777,
    "wslLinuxMode": false
  }
}

If you've set a custom agent directory via PI_CODING_AGENT_DIR, the settings are read from $PI_CODING_AGENT_DIR/settings.json instead.

| Key | Default | Description | |-----|---------|-------------| | port | 47777 | TCP port used for WSL→Windows communication. Change only if 47777 conflicts with another local service. | | wslLinuxMode | false | Set to true to use a Unix socket instead of TCP when under WSL (only for Chrome-inside-WSL setups). |

Available tools

| Tool | Description | |------|-------------| | chrome_tabs_context | List all open tabs (IDs, URLs, titles). Call first in every session. | | chrome_create_tab | Open a new empty tab | | chrome_close_tab | Close a tab by ID | | chrome_navigate | Navigate to a URL, or go back/forward | | chrome_computer | Mouse & keyboard actions + screenshots (click, type, scroll, key, drag, zoom, wait) | | chrome_read_page | Get the accessibility tree (ref IDs for clicking) | | chrome_get_text | Extract plain text from the page | | chrome_find | Find elements by natural language | | chrome_form_input | Set a value in a form field | | chrome_execute_js | Execute JavaScript and return the result | | chrome_console_logs | Read console.log / error / warn messages | | chrome_network_requests | Read XHR/Fetch requests made by the tab | | chrome_gif | Record an animated GIF of browser interactions | | chrome_resize_window | Resize the browser window | | chrome_upload_image | Upload a screenshot to a file input or drag-drop target | | chrome_file_upload | Upload local files to a file input | | chrome_shortcuts_list | List saved Claude shortcuts/workflows | | chrome_shortcuts_execute | Run a saved shortcut/workflow |

Usage example

> open github.com/trending and summarise the top 5 repos

pi will call chrome_tabs_context, chrome_navigate, chrome_get_text (or chrome_execute_js) and return a summary — all through the live Chrome tab you can see on screen.

Project structure

index.ts              — pi extension entry point; registers all tools & commands
src/
  settings.ts         — shared settings loader + WSL detection
  bridge.ts           — IPC/TCP client that forwards tool calls to the native host
  install.ts          — installs/updates the Chrome native messaging host manifest
  native-host.cjs     — Node.js process Chrome spawns (CommonJS, stdin/stdout protocol)
  native-host.js      — same as above in ES module syntax (used by tests)

Development

git clone https://github.com/your-org/pi-claude-extention
cd pi-claude-extention
npm install

Link it locally into pi for testing:

pi install ./pi-claude-extention

License

MIT