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.

💡 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

📋 Prerequisites

• Node.js ≥ 18 (ESM modules, fetch built-in)
• Pi Coding Agent (pi.dev)
• Chrome Extension — coming soon to the Chrome Web Store
• Google Chrome (or any Chromium-based browser)

📦 Installation

npm install pi-web-ui

Chrome Extension Setup

From the Chrome Web Store: Coming soon — link TBD.

Manual (development): Until the extension is published, load it from source:

1. Clone the Chrome extension repository.
2. Open chrome://extensions/.
3. Enable Developer mode (top-right corner).
4. Click Load unpacked and select the extension directory.
5. 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

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

Investigate a Network Error

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

Audit Console Output

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

Cross-Reference Page State with Code

1. Ask Pi: "Get the HTML of the current page and compare it with src/App.tsx — are there any mismatches?"
2. 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.