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.
- Source repo
- agegr/pi-web
- Stars
- ★ 8.1k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changes
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- You already have pi sessions spread across several projects and want to browse, resume, and tidy them in a browser grouped by project.
- Not a fit if
- Users wanting a general filesystem browser for the whole machine
- Teams exposing it to the internet without their own HTTPS proxy or VPN
- Source review
- 53/100 · Major gaps
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.
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.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pi Web This agent | 53 · Major gaps | CLIFree + model costs | ★ 8.1k | 2d ago | TypeScript | — |
| zerostack | 57 · Major gaps | CLIFree + model costs | ★ 1.7k | 1d ago | Rust | OpenAI API · Claude API |
| Kooky | 47 · Major gaps | Desktop appFree | ★ 655 | 25d ago | Swift | Codex · Claude Code |
| AgentDock | 32 · Major gaps | FrameworkFree + model costs | ★ 1.8k | 3mo ago | MDX | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
中文 基于 v0.14.2..v0.15.0 的提交整理。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 运行中也能切换模型：聊天框的模型选择器在运行时不再禁用，与 pi 的 TUI 一样，切换从这次运行的下一个请求起生效，推理级别本来就是这样。(#1527) - 侧聊标签随主会话恢复：右侧面板里打开的侧聊标签按主会话保存在当前浏览器标签页中，回到该会话或刷新页面时恢复（已删除的侧聊不会恢复）；同一项目内切换会话时保留子代理标签；未命名的侧聊在标签栏和 Agents 切换器里统一叫「Side chat 1」「Side chat 2」。(#1512，感谢 Tiger) - 拖动重排右侧面板标签：文件、终端和代理聊天标签可以拖到其他标签前后，顺序只在页面内保留。(#1511，感谢 Tiger) - 重排自定义提供商的模型：Settings › Models 里 models.json 提供商的模型行可以在桌面上拖动、用 Alt+↑/↓ 移动，或点「+ 模型」旁的 A–Z 按名称排序一次；保存后写回文件顺序，选择器和 pi 的 /model 跟着变。(6386fa4, #1479) …View on GitHub ↗ -
Release notes excerpt
中文 基于 v0.14.1..v0.14.2 的提交整理。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 模型选择器可切换「scoped | all」：设置了 enabledModels 时，聊天框的模型选择器顶部多出一行「scoped | all」，与 pi 的 /model 一样默认显示限定范围内的模型，点按或在筛选框里按 Tab 可切换到全部模型。选中范围外的模型会用于当前会话（新会话也可以从它开始），不会成为默认模型。(#1486, #1503，感谢 Salman Abdurrahman) - 在 Agents 列表里删除侧聊：侧聊行的标签切换按钮旁多了删除按钮，确认后只删除这个侧聊，主会话和其他侧聊保留；删除的正是主聊天里打开的侧聊时回到它的主会话。(#1507，感谢 谢凯文；48a158b) - 手机上的设置逐级全屏显示：手机上打开 Settings 先显示分区列表，再进入分区、再进入某一项的详情，每级全屏，标题栏有返回按钮和当前级别名称并居中显示；系统返回键返回上一级，切换时有滑动动画（开启减少动态效果时不动）。(9afc508, 1420b81) …View on GitHub ↗ -
Release notes excerpt
中文 基于 v0.13.0..v0.14.1 的提交整理。v0.14.0 标签打出后发布被取消，没有发布到 npm，也没有 GitHub Release，所以本说明包含自 0.13.0 以来的全部改动。 ```bash npm install -g @agegr/pi-web@latest ``` 新增 - 侧聊（side chat）：从当前会话分出一个侧聊，在右侧面板标签页里提问，带着主会话的全部上下文，主会话不受影响，运行中也能用。侧聊只保留主会话已有的只读和 shell 类工具（read、bash、grep、find、ls，Windows 上还有 powershell），不能编辑、写文件；只读的主会话分出的侧聊也没有 shell。入口有四个：/side 或 /side <问题>、选中文字后的「在侧聊询问」、运行中输入框旁的侧聊按钮、Agents 面板里的「新建侧聊」。侧聊不出现在侧栏里，在 Agents 列表中和子代理一起显示，第一条提问自动成为它的名字。(#1469，感谢 dingxiaobo；#1502) - 选中文字「引用」：选中回答里的文字后，原来的「在这里提问」改为「引用」，只插入 > 选中的文字，不再附带提问模板，提问、纠正、指示都可以接着写；多段引用各自成段。(#1502) …View on GitHub ↗