项目介绍

Pi-Remote 是 pi 的配套工具。pi 是一个终端编程智能体，Pi-Remote 不改它的源码、也不接管终端，而是通过 pi 官方扩展 API 挂载：会话始终留在本地 pi 进程里，浏览器拿到的是输出、工具调用和状态变化的实时镜像，同时可以把消息和命令发回会话。它面向已经在用 pi、又想从别的设备（通常是手机）盯住或操作长时间运行会话的人。

整体分三部分：运行在 pi 进程内的同步扩展负责转发事件并在本地执行远程命令；Node 中继负责认证和路由，不持有模型凭据或本地文件；中继提供 Web UI（组件分工）。同步协议和命令定义见 data-interface.md，终端与远程能力对照见能力清单。

除实时输出和排队/转向消息外，远程命令包括切换模型与思考等级、手动压缩上下文、创建/分叉/克隆会话、导航会话树、查看 token 与费用用量。多台机器可共用一个中继，UI 会列出每台设备、在线状态和会话；设备只在 attach 窗口开启期间可达。

快速使用

先安装 pi，Pi-Remote 不包含它（前置条件）：

npm install -g @earendil-works/pi-coding-agent

需要 Node >= 22.18。在 macOS 或 Linux 上不架服务器、单机跑通全流程：

npm install
npm run relay          # 扩展通道 127.0.0.1:7001，Web UI 7002
node deploy/setup.cjs ws://127.0.0.1:7001
deploy/sync-extension.sh   # 安装扩展到 ~/.pi/agent/extensions/
deploy/attach.sh           # 打开 attach 窗口，设备上线
deploy/start-pi.sh         # 在第二个终端启动 pi

Windows 下依次运行 npm install、npm run relay，再在第二个终端运行 deploy\start-pi.cmd（各平台命令）。打开 http://127.0.0.1:7002，用 .env 里的 viewer token 登录。若要在服务器上运行中继，systemd 配置、token 管理和排错见部署文档。

使用约束

扩展通道与 Web UI 使用不同 token，两个配置文件都已被 gitignore，扩展通道默认只绑定 127.0.0.1（安全模型）。持有 viewer token 的人都能向会话发消息，而 pi 带有工具权限，因此该 token 应当作密码对待；需要公网访问时，应使用私有网络、隧道或 TLS 反向代理，不要直接暴露 7002 端口。远程 bash 默认关闭，显式启用后工作目录被限制在会话目录和已注册项目内。对话内容默认不持久化，开启后保留 30 天。

已知限制：长对话未做虚拟化，UI 只挂载最近 300 条消息，更早的按页加载；除本地回环模式外，中继需要你自己维护一台服务器；没有多用户权限体系，设计上按个人单用户使用（已知限制）。项目使用 MIT 许可证。

HotRepo 点评

Pi-Remote 在 2026-11-02 的 TypeScript 新项目榜快照中记录到 53 颗新增 Star（窗口为 2026-11-01 至 2026-11-02），总量为 212。采样曲线从 2026-10-30 的约 102 颗起步并持续上升，在 2026-10-31 15:00 UTC 和 2026-11-01 14:00 UTC 前后各有一段明显跳升。项目没有全部语言日榜名次，讨论数据也没有匹配到线程，因此可用证据仅限于这段较短的 Star 序列。技术上值得注意的架构选择是：扩展、中继、UI 三者分离，pi 本身不被改动，远程界面可以替换；代价是在单用户前提下，viewer token 等于完整的发消息能力，部署前需要权衡这一点。