PiWeb

A modern web UI for the Pi Coding Agent.

English | 简体中文

---

PiWeb brings a sleek, feature-rich browser interface to the pi coding agent with zero modifications to the core Pi engine. Built with Next.js and Tailwind CSS.

Key Features

• Real-Time Streaming: Full SSE snapshots with ordered deltas, automatic replay via Last-Event-ID, real-time thinking process and inline tool execution cards.
• Composer & Input: Image attachments (paste, pick, drag-and-drop), 2-level model selector, model cycling forward/backward, queue management (steering / follow-up), and / slash commands.
• Decoupled Workspaces & Sessions: Group sessions by workspace folders, native system folder picker on Windows, rename/delete workspaces with centered confirmation modals, preserve sessions under "Ungrouped", and maintain empty workspaces independently.
• Session Exploration: Session tree branch visualization & navigation, editing or withdrawing a sent message (the conversation returns to just before it; the old branch stays in the session file), user message draft recovery, export session logs to JSONL / HTML, and trajectory views.
• Project Growth, One Git Commit per Round: Every round pi finishes is committed to a private ref in the workspace's own .git (your branches, HEAD and staging area stay untouched). The project panel shows what each round changed versus the previous one — files, +/− lines and the full diff — with your own edits between rounds recorded separately, and every prompt in the chat links to its round.
• pi's Eyes (Headless Browser Tools): With Chrome, Edge or Chromium installed, pi gets browser_open, browser_screenshot, browser_console, browser_click and browser_type. It opens your dev server in a headless browser, looks at the screenshot (a text outline for models without vision), reads console errors and failed requests, and fixes what it sees. Screenshots show up inline in the chat. Click Pick element on a screenshot to point at things yourself: PiWeb re-captures the page, you click an element, and it lands in the composer as a chip with its DOM path, source location (from build-time source attributes, React ≤18 / Vue / Svelte dev metadata, or a text search) and, for vision models, a cropped image.
• Comprehensive Settings:
  • General: Tool presets (Read Only / Workspace Write / Full Access), language (zh/en), appearance, enter key behaviors, and auto-compact.
  • Models: Manage 30+ built-in providers, custom providers in models.json, and OAuth logins (Claude, Codex, Copilot, etc.). Custom models can declare thinking support, which levels they offer and the value each level sends (pi's reasoning / thinkingLevelMap), plus image input. Thinking levels come straight from pi's built-in model metadata; new sessions start from the default model and level in pi's own settings.json (shared with pi in the terminal), and the model menu marks the defaults and can save the current pick as the new default.
  • Plugins & Skills: View and manage extensions and skills directly via Pi's built-in package manager.
• Security & Sandboxing: Optional password via PI_WEB_PASSWORD (browser login page, HTTP Basic for API clients) with a brake on repeated wrong passwords, origin validation on write actions, and strict path boundary checks.

Quick Start

Prerequisites: Node.js ≥ 22.19.0 (Node.js 24 recommended) and Git for repository and growth-history features. Growth history lives in the workspace's own .git: non-git folders are git init-ed automatically before the first commit, and one commit per round hangs off a dedicated refs/piweb/rounds/<key> ref without touching your branches, HEAD or staging area. Optional: Chrome, Edge or Chromium for pi's browser tools (Edge ships with Windows).

Install from npm (recommended)

npm install -g @rexvane/piweb
piweb

A global install prepares the production bundle once (during install, or on the first run if the script was skipped) and then starts in production mode. If that build fails, piweb reports it instead of falling back to a development server that cannot work without dev dependencies; retry with npm rebuild -g @rexvane/piweb. The package registers only the piweb command, so it never conflicts with the official pi CLI (npm i -g @earendil-works/pi-coding-agent) if you have both.

To update an npm install, stop piweb, run npm install -g @rexvane/piweb@latest, then start it again; when a newer release is out, Check for updates under Settings → General → PiWeb version shows this command. npm replaces the whole package folder, so do not update it under a running piweb. The pi engine is pinned by each PiWeb release and updates with it.

Inside this repository

npm install
npm run dev        # development server with hot reload

Or run a production build locally:

npm install
npm run build      # or: npm run build:release (staged, does not touch a running build)
npm start          # serves on http://127.0.0.1:30141 (auto-increments if busy)

CLI Options (bin/piweb.js)

-p, --port <port>      Listen port (default 30141, env PORT; auto-increments if in use)
-H, --hostname <host>  Bind address (default 127.0.0.1, env PI_WEB_HOSTNAME)
--dev                  Start in development mode (`next dev`; env PI_WEB_DEV=1; also used when no production build exists)
--no-open              Do not automatically open browser (env PI_WEB_NO_OPEN=1)
-h, --help             Show help

Environment variables: PI_WEB_PASSWORD enables a browser login session and HTTP Basic Auth for API clients (user pi). Wrong passwords are throttled for the whole server: after 10 new wrong ones, password checks allow one try every 30 seconds, and signed-in browsers are not affected. It is required for any non-loopback production bind address. Development mode is loopback-only, even with a password; if no production build exists, an external bind fails rather than falling back to an exposed development server. Use HTTPS or a trusted VPN for remote access. PI_WEB_EDITOR overrides the editor used by "open in editor" (default code). PI_WEB_BROWSER points pi's browser tools at a specific Chrome / Edge / Chromium executable (default: auto-detect); the tools only open loopback and private-network pages unless PI_WEB_BROWSER_ALLOW_PUBLIC=1 is set. Without a password, PiWeb only accepts requests whose Host is loopback.

GET /api/health exposes only a fixed service identifier for credential-free startup probes. Runtime versions are available from the authenticated /api/version endpoint. Tool presets limit the tools offered to the agent; they are not an operating-system sandbox, and installed extensions run with the server process's permissions.

Model catalog discovery blocks loopback, private, and reserved network addresses by default. If you intentionally use a local model gateway, set PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1 before starting PiWeb. This relaxes the discovery endpoint only; use it only on a trusted PiWeb instance.

Growth history in Git

Each round is a regular commit, so any Git tool can read the history:

git for-each-ref refs/piweb/rounds/        # this workspace's ref (one per worktree)
git log --stat refs/piweb/rounds/<key>      # one commit per round: title = your prompt, Piweb-* trailers = session / status

Builds before rounds kept per-tool snapshots under refs/piweb/growth/ plus .git/piweb/ledger.jsonl; the current version no longer reads them. To remove them:

git for-each-ref --format="delete %(refname)" refs/piweb/growth/ | git update-ref --stdin
rm .git/piweb/ledger.jsonl

Development

npm run dev        # Run Next.js in development mode
npm run typecheck  # TypeScript check
npm test           # Service, protocol and component regressions
npm run check      # Full check (types + tests + build)
npm run build:release # Validate and stage a production build without replacing the running build

Status and known limitations (2026-10-07)

The audit follow-up is merged into this branch and has been through an isolated release plus a local production deployment. It covers the production login build, upload integrity through the Next.js proxy, per-session extension isolation and tool-policy reloads, lossless model/settings writes, composer and pending-extension-UI lifecycle, Git/Growth/diff correctness, and isolated release preparation.

Since then PiWeb gained element picking on pi's browser screenshots, thinking levels that follow pi's own model settings, and editing or withdrawing sent messages. Deleting a skill now follows pi's skill layout (a single-file skill removes only that file), npm installs build and check for updates correctly, and password checks are throttled. Saving the model configuration in Settings now updates sessions that are already open; answers are laid out as Markdown while they are still being written; and emptying a built-in provider override removes the whole block (it used to write an empty block that pi rejects, so the save failed).

Latest validation: TypeScript checking passes locally on Windows with 496 tests across 79 files (one more skipped: a growth-history test that needs symlink privileges; on Linux the skipped one is a Windows-only PowerShell encoding test); CI runs the full pipeline (types, tests, production build) on Linux and Windows with Node.js 22.19.0 and 24, and passes. The real-browser tests need Chrome, Edge or Chromium and are skipped without one.

Known limitations: saving the model configuration normalizes it to plain JSON (comments are not preserved, data is); updates replace dependencies in place during a maintenance window rather than being zero-downtime; a custom tool allowlist lives only for the session lifetime; third-party extension module globals are not isolated. Editing or withdrawing a sent message rewinds the conversation, not the files the agent already changed (use the growth history for those). Password throttling is server-wide, so while someone keeps guessing, password sign-in waits for everyone. Non-image files dropped into the composer are kept in ~/.pi/agent/web-uploads/ because sessions refer to them by path; remove old ones by hand. Growth history: when two sessions run in the same workspace at once, changes can land in the other session’s round; changes made with shell commands inside a round only show up in that round’s summary (edit/write diffs are still in the conversation). Browser tools are offered only under the Workspace Write and Full access tool presets; the headless browser uses a temporary profile, so after PiWeb restarts you need to sign in to the app under test again; screenshots are stored in the session JSONL like other images; the address policy only stops the tools from opening public addresses and does not restrict what the page itself loads.

Production builds and updates

Use npm run build:release when preparing a build while PiWeb is running. It validates types and tests, builds into a fresh .next-releases/<id> directory, and only then publishes the build selection for the next start. It does not restart the server or replace the output used by an existing process. npm start uses the last successfully prepared release; after a failed or interrupted release attempt it reports the problem instead of silently serving a stale build. Correct the error and run npm run build:release again to recover.

The in-app updater uses the same validation path. Source files and npm dependencies are still updated in the installation directory, so perform updates during a maintenance window with no running agent turns. This is not a fully isolated zero-downtime deployment system. Restart PiWeb manually after a successful update; running processes do not automatically switch to the new build. This applies to Git checkouts: for an npm install the updater only compares with the registry and shows the npm command (see Install from npm).

CI runs the full checks on Linux and Windows with Node.js 22.19.0 and 24. Ordinary npm run build still uses .next, so do not run it against an installation whose active production process is using that directory.

Architecture

Browser (React 19 + Tailwind, src/components)
   │  REST commands (POST /api/agent/[id]) + SSE streams (GET /api/agent/[id]/events)
   ▼
Next.js Server (src/app/api, src/lib)
   ├─ agent-manager    AgentSession pool: lazy startup, event translation, idle eviction
   ├─ session-reader   Direct read ~/.pi/agent/sessions/**.jsonl (cold render without running agent)
   ├─ trajectory       Trajectory ledger + server-side timing (TTFT / decode)
   ├─ skills/prompts   Skills & Prompt template discovery + frontmatter toggles
   ├─ models-service   Model catalogue, auth, OAuth bridge & models.json
   ├─ security-service Tool presets & project trust
   ├─ plugins-service  Pi package management (DefaultPackageManager) & extension registry
   ├─ workspace-store  Persistent workspaces registry & native folder picker
   ├─ growth-*         Project growth: one commit per round on refs/piweb/rounds/<key>, timeline via git log
   ├─ browser/*        pi's eyes: headless Chrome / Edge over a CDP pipe, browser tools + screenshots
   ▼
@earendil-works/pi-coding-agent  (Official Pi SDK, zero engine modifications)

License

MIT License