把PI编程Agent的终端会话搬到浏览器：pi-web 本地Web界面 | pi-web

📌 项目地址：agegr/pi-web | ⭐ 2,028 颗星 | 🔧 TypeScript | 📜 未标注

为什么需要 pi-web

如果你在用 pi（一个开源的 coding agent），可能会遇到这些烦心事：

• 想回顾之前某个项目的对话，得在终端翻历史、找 session 路径，效率低。
• 想从某一步分叉出去尝试新方案？终端里做分支管理要么复制 session 文件，要么重新跑 agent，不直观。
• 边和 agent 聊天边查看项目文件？终端里只能用 cat 或 less，无法预览图片、PDF、文档格式。
• 切换 Git worktree 后，新 session 和文件浏览往往不会自动跟随，需要手动重新指向。

pi-web 就是一个在本地运行的 Web 界面，它直接读取 pi agent 的 session 文件，把上述操作变成浏览器里点一点的事。

核心功能

🔙 会话回溯与分支

• 按项目浏览所有历史 session，不用再翻终端。
• 可以从任意一条历史消息继续对话，或者 fork 出一个新会话，尝试不同的方向。
• 会话的状态（上下文用量、花费、压缩状态、系统提示）都在顶部栏清晰展示。

🗂️ 文件浏览与预览

• 左侧可以浏览项目文件，右侧预览源码、文档、图片、音频、PDF。
• 文件访问范围被限制在所选项目目录以及 session 中出现的工作目录，保证安全。

🛠️ Git Worktree 管理

• 侧边栏可以直接切换 Git worktree，新 session 和文件浏览器会自动跟随当前 checkout。
• 对于在多个分支间切换开发场景非常实用。

⚙️ 配置界面化

• 管理模型、API key、登录凭据、模型测试、技能开关，全都从 Web UI 操作，不用再记终端命令。

实际用法

启动（无需安装）：

npx @agegr/pi-web@latest

这会自动在 http://localhost:30141 启动，并在就绪时尝试打开浏览器。

全局安装后启动：

npm install -g @agegr/pi-web
pi-web

常用选项（全部来自 README 原文）：

pi-web --port 8080              # 自定义端口
pi-web --hostname 127.0.0.1     # 仅本地访问
pi-web -p 8080 -H 127.0.0.1     # 组合选项
pi-web --no-open                # 不自动打开浏览器
PORT=8080 pi-web                # 支持环境变量
PI_WEB_NO_OPEN=1 pi-web         # 后台运行时有用

HTTP 代理配置（用于服务端模型请求）：

# macOS / Linux
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@latest

# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

与纯终端 pi agent 的对比

pi-web 并没有替代 pi agent 的 CLI 核心功能，而是补充了一个可视化的操作层——对话、编辑器、文件预览都保留在同一个界面，且 session 文件和 agent 目录完全兼容。

需要注意的事项

• 数据目录：默认读取 ~/.pi/agent/sessions。如果 pi agent 使用的是自定义目录，需设置环境变量 PI_CODING_AGENT_DIR。
• Session 格式：文件存储为 ~/.pi/agent/sessions/<项目>/<会话>.jsonl，不要手动修改。
• 模型配置：Models 面板读写的是 pi agent 目录下的 models.json，模型列表和默认值来自 pi 的配置。
• 文件访问限制：文件浏览和预览被限制在所选项目目录和 session 中出现的工作目录，并非整个文件系统。
• 许可证：未在 README 中明确列出许可证信息，使用前需确认或查看仓库 LICENSE 文件（README 未提及，需自行检查）。

适合谁用

如果你已经在使用 pi coding agent（尤其是多项目、多分支场景），并且希望提升会话管理和文件预览体验，pi-web 是官方提供的配套 GUI。它不需要额外配置，启动后直接读取现有 session 文件，能与 CLI 无缝切换使用。