pi-web-codex
v0.1.34
Published
A local Web Host for Pi coding-agent workflows.
Maintainers
averyyyReadme
pi-web-codex
为 Pi coding-agent 工作流打造的本地 Web Host
在快速、可检查、可脚本化的浏览器界面中运行 Pi 会话、项目、插件与开发工具，数据始终留在本机。
English · Pi Packages · NPM · GitHub
先看界面
以下为 2026 年 9 月 7 日在 macOS 本机运行 pi-web-codex 0.1.3 的真实浏览器截图。项目首页处于尚未选择模型、尚未开始会话的状态；不是设计稿或生成图。
核心亮点
| | 能力 | 实际体验 | | --- | ------------------------ | -------------------------------------------------------------------------------------------- | | ⚡ | 实时 Pi 会话 | 支持提示词流式输出、工具事件、中止、重试、压缩、模型与思考级别控制。 | | 🧭 | 项目与会话历史 | 浏览 JSONL 项目、全文搜索、fork/clone 会话、切换分支，并导入导出 JSONL 或 HTML。 | | 🧩 | 原生 WebUI 插件 | 在浏览器中渲染对话框、编辑器、组件和浮层，同时保留 Pi 原生 TUI 作为回退路径。 | | 🔌 | 原生 MCP 与 codemode | 配置 Pi 的 stdio 或 Streamable HTTP 服务，选择工具暴露方式，查看 JavaScript 与内部工具调用。 | | 🛠️ | 开发者可观测性 | 在一个界面中查看只读文件、Git 分支/提交/worktree、环境信息与运行时诊断。 | | 📦 | 本地优先交付 | 独立 CLI、可安装 PWA、原子化设置、可选通知，无需托管账号。 |
安装与运行
需要 Node.js 22.19+ 或 Node.js 24+。不支持 Node.js 23。
发布门禁在 Windows x64、macOS arm64 和 Ubuntu 22.04 x64（glibc） 上安装同一个 tarball，验证两个 runtime worker 和真实终端。该矩阵尚未覆盖其他 CPU 架构及使用 musl 的 Linux 发行版。浏览器界面适配桌面、平板和手机宽度。
npm install --global pi-web-codex
pi-web-codex命令会在后台启动默认实例，等待服务就绪后返回；关闭启动终端后，服务仍会继续运行。所有实例共用全局 CLI 安装，通过以下命令统一管理：
pi-web-codex --port 3000
pi-web-codex list
pi-web-codex start <id>
pi-web-codex stop <id>
pi-web-codex stop
pi-web-codex --help--port 创建或启动绑定该端口的实例。list 显示已保存实例的 ID、端口以及运行中／已停止状态。start <id> 恢复指定实例；stop <id> 停止指定实例，不带 ID 的 stop 只停止默认实例。--help 列出全部可用指令和选项。
每个实例分别记忆 WebUI 设置，包括默认 runtime、PiServer URL 和凭据。例如，1816 端口可以连接 Pi Client，1818 端口可以使用 Pi。在实例设置页保存的修改会在停止、重新启动后保留；停止实例不会删除其数据或配置。
也可以作为 Pi package 安装，并在会话里启动：
pi install npm:pi-web-codex如果 Pi 会话已经打开，先运行 /reload（或重启 Pi）加载新安装的扩展，再运行 /pi-web-codex。服务就绪后会打开配置的地址（默认 http://127.0.0.1:1816）。使用 pi-web-codex --help 查看全部 CLI 选项。
Agent 设置与 MCP
设置 → Agent 配置 Pi 与 Pi Client 的工具选择、codemode、压缩、缓存预热、队列、图片处理和请求行为。设置通过 Pi Agent 目录共享；可信项目设置遵循 Pi 的覆盖规则。保存 Agent 或 MCP 设置后，空闲会话立即重新加载，运行中的会话在本轮结束后应用。
设置 → MCP 编辑 Pi agent 目录或选定项目 .pi 目录中的原生 mcp.json。Pi 在项目信任后连接项目服务。服务默认通过 codemode 暴露工具；direct 将工具直接声明给模型，deferred 通过工具搜索按需加载。在会话中发送 /mcp 查看连接状态和工具数量；/mcp login 名称、/mcp logout 名称、/mcp reconnect 名称 管理认证与重连。
WebUI 加载 Pi 内置的 MCP、codemode 和工具搜索扩展。WebUI 会话不支持 pi-mcp-adapter。MCP 凭据和环境变量替换遵循 Pi 原生配置与 OAuth 存储方式。
旧 WebUI MCP 条目在 config.json 中保留为未启用的迁移数据；有条目时，设置 → MCP 显示该文件路径，可通过页面表单将服务添加到 Pi 原生 mcp.json。
更新 WebUI
通过安装包启动的服务会检查 npm 上是否有更新的稳定版本。有新版时，侧栏会显示蓝色更新按钮；点击后自动安装并在原地址重启 WebUI，页面自动重连并恢复未发送的对话草稿。
Pi 扩展和 pi-web-codex 命令使用同一份全局 npm 安装。更新过程中的临时安装仅用于校验与恢复；只有全局包、CLI 和运行中的服务都报告目标版本，才算更新完成。
下载准备期间，当前服务继续运行。切换版本前，需要等待执行中的任务结束并关闭终端。安装或启动失败会明确显示错误，更新器会尝试恢复原安装和数据库。配置、凭据及独立的 PiServer 服务会保留。源码开发服务器不支持自动更新安装包。
本地开发
npx [email protected] install
npx [email protected] dev打开 http://127.0.0.1:1816，发布前运行以下检查：
npx [email protected] test
npx [email protected] typecheck
npx [email protected] lint
npx [email protected] build完整的打包发布检查：
npx [email protected] release:verify该命令会构建便携 standalone 目录，验证 NPM tarball 同时包含两个已编译 worker 且不含 TypeScript 业务源码，将其安装到临时全局目录，通过健康检查启动已安装的 CLI，初始化两个 runtime worker，并实际检查终端启动与输出。
扩展 Host
WebUI Extensions 是现有 Pi Extensions 的可选适配器，可以渐进式地用浏览器原生 Shadow DOM 视图替换已知命令和渲染器。当适配器缺失、禁用、不兼容、冲突或运行时失败时，Host 会保留原始 Pi 行为与 Virtual TUI。
项目状态
当前里程碑覆盖生产级 Host 生命周期、健康与设置 API、真实 Pi JSONL 项目与独立任务、隔离 Pi SDK worker、会话生命周期操作、插件设置、MCP 管理、项目 Git/文件检查、PWA 缓存和运行时诊断。所有 UI 都对应真实的后端操作。