pi-web-ui

A local bridge that gives Pi Coding Agent direct browser control — so you can work in your terminal and your browser without ever breaking context.

📋 Prerequisites

Node.js ≥ 18 (ESM modules, fetch built-in)
Pi Coding Agent (pi.dev)
Chrome Extension — Here
Google Chrome (or any Chromium-based browser)

💡 Philosophy

Your session shouldn't be confined to one tool. When you're debugging a frontend issue, you switch between your terminal (where Pi lives) and your browser (where the problem is). Every switch costs context. Every copy-paste loses nuance.

pi-web-ui eliminates that friction by turning your Chrome browser into a first-class tool for Pi. The bridge runs entirely on your machine — no data leaves to a third-party server — and enforces permissions so sensitive operations (cookie access, script evaluation, raw CDP commands) require your explicit approval.

Core principles:

Local-first privacy — The bridge is a local WebSocket/HTTP server on 127.0.0.1. All communication stays on your machine.
Seamless terminal ↔ browser sessions — Start a session from Pi's terminal, continue it in the Chrome side panel, resume it hours later. One conversation, multiple surfaces.
Permission-aware by default — Cookie and storage access are opt-in. Script evaluation and raw CDP commands require confirmation. All sensitive actions are audit-logged.
Browser as a tool, not a toy — Pi gets structured access to page content, network requests, console logs, screenshots, and the full Chrome DevTools Protocol.

🔌 What It Does

pi-web-ui is the server-side bridge that connects three pieces:

Component	Role
Pi Coding Agent	Sends prompts, receives responses, requests browser tools
pi-web-ui (this package)	Local bridge — manages sessions, enforces permissions, relays messages
Chrome Extension	Side panel UI + executes browser operations via Chrome DevTools Protocol

┌───────────────────────────┐         WebSocket          ┌──────────────────────┐
│   Chrome Extension        │ ◄──── ws://127.0.0.1 ───►  │   Local Bridge       │
│   (side panel UI)         │         (port 43117)       │  (pi-web-ui)         │
│                           │                            │                      │
│  • Debugger client        │   browser_tool_request     │  • Pi SDK session    │
│  • Network capture        │ ◄───────────────────────── │  • Tool executor     │
│  • Console capture        │   browser_tool_response    │  • Permission gates  │
│  • Session management     │                            │  • Session registry  │
└───────────────────────────┘                            └──────────────────────┘
         ▲                                                ▲
         │                                                │
   Chrome tabs ◄──────── Chrome DevTools Protocol ────── Pi Coding Agent

📦 Installation

pi install npm:@isr4el-silv4/pi-web-ui

Chrome Extension Setup

From the Chrome Web Store: Here.

Manual (development): Load it from source:

Clone the Chrome extension repository.
Open chrome://extensions/.
Enable Developer mode (top-right corner).
Click Load unpacked and select the extension directory.
Click the Pi Web UI extension icon (or right-click → "Add to toolbar") to pin it.

🚀 Quick Start

1. Start the Bridge

From a Pi terminal session, run:

/pi-web-ui start

This spawns the local bridge on port 43117 and opens Chrome with the side panel.

2. Open the Side Panel

Click the Pi Web UI extension icon in Chrome. The side panel should show Bridge online when connected.

3. Pick Your Working Directory

Click Browse… in the side panel header to select your project directory. This sets the cwd for the Pi session and determines where session files are saved.

4. Start Working

Send a prompt from either:

Pi's terminal — type your message as usual.
The Chrome side panel — use the chat input in the extension.

Pi responds in both places, and the conversation stays synchronized.

⌨️ Usage

CLI Commands

The pi-web-ui binary provides lifecycle management:

Command	Description	Example
`start`	Start the bridge and open Chrome	`/pi-web-ui start`
`stop`	Stop the running bridge	`/pi-web-ui stop`
`status`	Check if the bridge is running	`/pi-web-ui status`
`open`	Open Chrome with the side panel (bridge must be running)	`/pi-web-ui open`

🛠️ Browser Tools

Pi gains access to these browser operations on your active tabs:

Page Inspection

Tool	Description
`browser_get_page_text`	Get the visible text content of the current page
`browser_get_page_html`	Get the full HTML of the current page
`browser_get_selection`	Get the currently selected/highlighted text
`browser_capture_screenshot`	Capture a screenshot of the current tab

Example — Ask Pi to inspect a page:

"What does the current page say about the error message?"

Pi calls browser_get_page_text, reads the content, and responds with an analysis.

Tab Management

Tool	Description
`browser_list_tabs`	List all open browser tabs
`browser_get_current_tab`	Get info about the active tab (including debugger attachment status)

Example — Switch context:

"List my open tabs and summarize what each one is about."

Console & Network Debugging

Tool	Description
`browser_get_console_logs`	Get buffered console logs from the browser
`browser_clear_console_log_buffer`	Clear the console log buffer
`browser_start_network_capture`	Start capturing network requests
`browser_stop_network_capture`	Stop network capture
`browser_get_network_requests`	Get all captured network requests
`browser_get_network_request`	Get details for a specific request by ID
`browser_get_network_response_body`	Get the response body of a specific request

Example — Debug a failing API call:

"Check the network requests for any failures and show me the error response."

Pi attaches the debugger, captures network traffic, filters for errors, and shows you the response — all without you touching DevTools.

Example — Console errors:

"Are there any errors in the browser console?"

Debugger & Script Evaluation

Tool	Description	Requires Confirmation
`browser_attach_debugger`	Attach Chrome debugger to a tab	No
`browser_detach_debugger`	Detach debugger from a tab	No
`browser_get_attached_tabs`	List tabs with debugger attached	No
`browser_evaluate_script`	Execute JavaScript in the page context	Yes
`browser_send_cdp_command`	Send raw Chrome DevTools Protocol commands	Yes

Example — Evaluate a selector:

"Run document.querySelectorAll('.card').length in the current tab and tell me how many cards there are."

A confirmation prompt appears in the side panel. Approve it, and Pi executes the script and reports the result.

Cookies & Storage (Opt-In)

Tool	Description	Permission
`browser_get_cookies`	Get cookies for the current page or domain	Header toggle
`browser_get_local_storage`	Get localStorage entries	Header toggle
`browser_get_session_storage`	Get sessionStorage entries	Header toggle

Enable these via the Cookie access and Storage access checkboxes in the side panel header. They are disabled by default.

🎨 Frontend Development Workflows

Here are common scenarios where pi-web-ui saves time:

Debug a Visual Bug

Open the page with the bug in Chrome.
Ask Pi: "Take a screenshot of the current tab and tell me what's wrong with the layout."
Pi captures the screenshot, analyzes it, and suggests fixes.
Apply fixes in your editor, refresh, and ask Pi to verify.

Investigate a Network Error

Reproduce the error in your browser.
Ask Pi: "Check the network requests for any failures and show me the error response."
Pi reads the captured requests, identifies the failing call, and shows you the response body and status code.

Audit Console Output

Ask Pi: "Read the browser console — are there any warnings or errors?"
Pi fetches console logs, filters by severity, and summarizes findings.

Cross-Reference Page State with Code

Ask Pi: "Get the HTML of the current page and compare it with src/App.tsx — are there any mismatches?"
Pi reads the live DOM, reads your source file, and highlights discrepancies.

📂 Session Management

Sessions are tied to your working directory and persisted as JSONL files.

New session — Click + New Session in the side panel, or run /pi-web-ui start in a new directory.
Resume session — Pick a previous session from the dropdown to continue where you left off.
Switch surfaces — Start a conversation in Pi's terminal, continue it in the Chrome side panel. History is synchronized.
Session history — When resuming, the full conversation (including tool calls and results) is loaded and displayed.

🔒 Permissions & Safety

Operation	Default	Control
Page inspection (text, HTML, screenshot)	Allowed	Always
Tab management	Allowed	Always
Console logs	Allowed	Always
Network capture	Allowed	Always
Cookie access	Disabled	Header toggle
Storage access	Disabled	Header toggle
Script evaluation	Requires confirmation	Per-request prompt
Raw CDP commands	Requires confirmation	Per-request prompt

All confirmed sensitive actions are recorded in an audit log on the bridge side, so you can review what was executed and when.

📄 License

Apache 2.0 — see LICENSE for details.

@isr4el-silv4/pi-web-ui

Signals

Download trend

README