Pi Web
A local browser UI for the pi coding agent that reuses the same config and session files, so you can browse, resume, and branch conversations.
Per-dimension scores and reasoning
README states loopback-only default binding, scoped file browser, and the model-test route enforces request-origin and JSON content-type checks, so least privilege and data-flow transparency are reasonably handled; however binding 0.0.0.0 relies on an optional plaintext password over HTTP with no forced confirmation or encryption, so least_privilege and user_confirmation are not full. Dependencies are mostly pinned but include a node-pty beta and a very new next, with no audit or mitigation notes, so dependency_security is 1. External effects (model calls, file writes, git worktrees) are described but no rollback/undo mechanism exists, so rollback is 1. Source attribution has LICENSE and repo metadata but publisher identity is unverified, so source_attribution is 2.
README, package.json, and CI agree on Node version, scripts, and port, so self_consistency is 2; the model-test route returns structured errors for timeout, failure, and missing API key, so failure_messages is 2. Dependency availability depends on external @earendil-works packages and a beta node-pty with no lockfile or mirror guidance, so dependency_availability is 1.
Audience and scenarios for pi users and local developers are clear, capability boundaries (not a general file browser, shared pi config) are stated, and environment_fit covers macOS/Linux/Windows plus proxy settings, so 2; trigger conditions (when the browser auto-opens, worktree switch conditions) are only partially documented, so trigger_precision is 1.
Install notes are thorough (npx, global install, update, uninstall, option table) and the license is complete MIT, both 3; information architecture and repo layout are clear, 2; naming is stable but version is only 0.9.1 with no CHANGELOG, so versioning_changelog is 1; examples and FAQ are sparse, so examples_and_faq is 1; known limitations exist as notes but are not systematic, 2; maintenance responsibility is unclear (unverified publisher), so maintenance_responsibility is 1.
Output usability is shown by concrete session browsing, export, and preview features, 2; marginal value over the pi CLI (browser UI, i18n, worktrees) is clear, 2; but cost-benefit lacks performance, resource, or alternative comparisons, so cost_benefit is 1.
README claims partially map to code and CI, but there are no test results, benchmarks, or third-party validation, so claim_traceability and cross_source_corroboration are 1; fact/inference separation is only moderate, so fact_inference_separation is 1.
- Binding 0.0.0.0 relies on an optional plaintext password without transport encryption; exposing it to a network is high risk—use an HTTPS reverse proxy or VPN.
- Dependencies include a node-pty beta and a very new next, with no audit or lockfile evidence; verify before upgrading.
- Publisher identity is unverified and maintenance responsibility/update path is unclear, creating long-term maintenance uncertainty.
- No CHANGELOG and only informal known limitations make version evolution and compatibility changes hard to track.
What does this agent do, and when should you use it?
Pi Web is a locally hosted browser interface for the pi coding agent. It reads pi's own local configuration and session files, so conversations shown in the browser match what pi has on disk and can be resumed directly. The session workspace groups conversations by project and surfaces running state, context usage, cost, and compaction details, with two ways to branch: a new independent session file or an in-session branch edited from an earlier message. Beyond chat, it bundles project file tools: browse and upload files, inspect Git diffs, preview source, Markdown, images, audio, PDFs, and DOCX, and switch Git worktrees from the sidebar. Model providers, credentials, model tests, plugin packages, and skills are all configurable in the web UI, which ships in English, Simplified Chinese, and Traditional Chinese. It runs as a local Node service bound to 127.0.0.1:30141 by default and starts with a single npx command.
Pi Web runs a Next.js server (app/ holds the UI and API routes) that reads pi's agent directory (default ~/.pi/agent, overridable with PI_CODING_AGENT_DIR) and renders session files stored as sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl, grouped by project. From there you can resume, rename, export, and delete sessions and inspect running state, context usage, cost, and compaction details; "New session" forks an independent session file from an earlier message, while "Edit from here" creates a branch inside the current session. The file panel browses and uploads files in working directories, shows Git diffs, previews source, Markdown, images, audio, PDFs, and DOCX with automatic refresh, and the sidebar switches between Git worktrees of the same repository. The Models panel reuses pi's model, settings, and credential storage for provider login, API keys, model tests, and plugin/skill management. Server-side model and API requests honor HTTP_PROXY, HTTPS_PROXY, and NO_PROXY; optional PI_WEB_PASSWORD enables browser login, and API clients can use Basic Auth with username pi.
- You already have pi sessions spread across several projects and want to browse, resume, and tidy them in a browser grouped by project.
- You want to fork at a specific historical message: save an independent session with "New session", or create an in-session branch with "Edit from here" and compare outcomes.
- You need to review a Git diff from an agent run and preview the changed source, Markdown, or images without opening an editor.
- You keep multiple Git worktrees of one repository and want to switch checkouts from the sidebar while keeping sessions of that repo grouped together.
- You prefer to configure provider login, API keys, model tests, and plugins/skills in a web panel instead of hand-editing CLI configuration.
- You want remote access on a trusted LAN by binding 0.0.0.0 with a long random password, or through an HTTPS reverse proxy or VPN.
What are this agent's strengths and limitations?
- It reuses pi's own model, settings, and credential storage, so configuration changes are visible to both interfaces with no account migration or sync step.
- Session handling is granular: project grouping plus resume, rename, export, and delete, with a real distinction between an independent "New session" file and an "Edit from here" in-session branch.
- File-side tooling is substantial: Git diffs, Git worktree switching, and previews for source, Markdown, images, audio, PDFs, and DOCX with automatic refresh.
- It binds to 127.0.0.1 by default and exposes explicit controls for exposure and timeouts via PI_WEB_PASSWORD, PI_WEB_ALLOWED_HOSTS, and PI_WEB_IDLE_TIMEOUT_MS.
- The UI ships in English, Simplified Chinese, and Traditional Chinese and follows the browser language initially, which lowers the barrier for mixed teams.
- It depends on pi's directory layout (jsonl session files under ~/.pi/agent by default) and must run in the same filesystem environment as pi to share existing sessions.
- It requires Node.js 22.19.0 or newer and network access for server-side model and API calls, so it is unusable fully offline.
- Password auth is access control only and does not encrypt traffic; internet exposure requires your own HTTPS reverse proxy or VPN and correct PI_WEB_ALLOWED_HOSTS setup.
- The file browser is deliberately limited to working directories selected in Pi Web and project/session roots it already knows, not the whole filesystem.
- Do not run next build or npm run build during normal development because it writes to .next/ and can interfere with the dev server, so the build workflow differs from a typical Next.js project.
How do you install or deploy this agent?
Node.js 22.19.0 or newer is required; verify with node --version. Run without installing:
npx @agegr/pi-web@latestOr install the CLI globally:
npm install -g @agegr/pi-web@latest
pi-webTo update, stop the running process with Ctrl+C and rerun the install command; to uninstall, run npm uninstall -g @agegr/pi-web. The CLI opens a browser once the server is ready; otherwise open http://127.0.0.1:30141. If no model provider is configured yet, sign in or add an API key in the Models panel first.
How do you use this agent?
Start with npx @agegr/pi-web@latest; the server listens only on 127.0.0.1:30141 by default. Common options: pi-web --help prints startup options; --port/-p or PORT sets the port; --hostname/-H or PI_WEB_HOSTNAME sets the bind address; --no-open or PI_WEB_NO_OPEN=1 disables automatic browser opening. Remote access example:
PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0Password auth does not encrypt the connection: never expose it over plain HTTP to the internet, use HTTPS via a trusted reverse proxy or VPN, and add the exact external hostname to PI_WEB_ALLOWED_HOSTS when a proxy forwards it. Other variables: PI_WEB_SKIP_VERSION_CHECK=1 disables update checks, and PI_WEB_IDLE_TIMEOUT_MS sets the idle timeout (default 600000 ms, 0 disables it). Proxy example:
HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 NO_PROXY=localhost,127.0.0.1 npx @agegr/pi-web@latestFor development: npm install then npm run dev; run npm test, node_modules/.bin/tsc --noEmit, and npm run lint. Do not run next build or npm run build during normal development.
How does this agent compare with similar options?
The README names the upstream pi coding agent (https://github.com/earendil-works/pi): Pi Web does not run agent logic itself but acts as its local browser front end over the same configuration and session files. No other alternatives are named.