Xpropel/Pi-Remote

选用指南

AI 根据 README 整理 · 2026/10/29 05:01:43

适用场景

适用于需要从浏览器远程查看和控制 pi 终端会话的场景，支持多设备同时连接，可通过局域网或临时公网 URL 访问。

查看 README 依据

Pi-Remote attaches to a running pi session through pi's official extension API. It does not modify pi's source code and does not take over the terminal. The session stays in the local pi process at all times; the browser shows a real-time mirror of that session and can send messages and commands back to it, including switching models, changing the thinking level, compacting context, and navigating the session tree. The local side runs on Windows, macOS, and Linux, and several machines can be connected at the same time.

- **Serverless mode** — no cloud server required: the relay runs on your own computer (one-time `setup --local`), your phone connects over the LAN on the same Wi-Fi, and when you leave home you can turn on a Cloudflare Tunnel on demand and open a temporary public URL by QR code (the URL changes on every start, and closing the attach window stops everything). - **Desktop and mobile UI** — separate layouts for desktop and mobile, with six skins: Cursor, Claude, and Codex looks in dark and light.

目标用户

面向使用 pi 终端编码代理的用户，需要先安装 pi。

查看 README 依据

> **Relationship to pi**: Pi-Remote is a companion tool built for [pi](https://github.com/earendil-works/pi), Earendil's terminal coding agent, on pi's official extension API, for people who use pi. It is not a fork, variant, or replacement of pi: pi itself keeps running in the local terminal, and Pi-Remote only adds a remote mirror and control surface for it. <p align="center"> <img src="assets/readme/design-single.png" alt="Pi-Remote UI design mockup" width="100%"> </p> <p align="center">_{UI design mockup: desktop on the left, mobile on the right.}</p> ## Features

**Prerequisite: install pi on your device first.** Pi-Remote is a companion tool for [pi](https://github.com/earendil-works/pi) and does not include pi itself. Before using Pi-Remote, install pi on the machine you want to control and make sure it runs: ```bash npm install -g @earendil-works/pi-coding-agent ``` Requirements: Node ≥ 22.18. The following runs the full loop on one machine, no server involved: Windows: ```powershell npm install npm run relay # 127.0.0.1:7001 (extension channel) and 7002 (web UI) deploy\start-pi.cmd # in a second terminal: start pi ```

使用方式

通过命令行安装和运行，包括启动 relay、安装扩展、打开 attach 窗口，然后通过浏览器访问 UI。

查看 README 依据

**Prerequisite: install pi on your device first.** Pi-Remote is a companion tool for [pi](https://github.com/earendil-works/pi) and does not include pi itself. Before using Pi-Remote, install pi on the machine you want to control and make sure it runs: ```bash npm install -g @earendil-works/pi-coding-agent ``` Requirements: Node ≥ 22.18. The following runs the full loop on one machine, no server involved: Windows: ```powershell npm install npm run relay # 127.0.0.1:7001 (extension channel) and 7002 (web UI) deploy\start-pi.cmd # in a second terminal: start pi ```

macOS / Linux: ```bash npm install npm run relay node deploy/setup.cjs ws://127.0.0.1:7001 deploy/sync-extension.sh # install the extension into ~/.pi/agent/extensions/ deploy/attach.sh # open the attach window; the device comes online deploy/start-pi.sh # in a second terminal: start pi ``` Open `http://127.0.0.1:7002` and enter the viewer token from your `.env`. For running the relay on a server (systemd setup, token management, troubleshooting), see [deploy/README.md](deploy/README.md). ## Security model

部署要求

需要 Node.js ≥ 22.18，并预先安装 pi。

查看 README 依据

**Prerequisite: install pi on your device first.** Pi-Remote is a companion tool for [pi](https://github.com/earendil-works/pi) and does not include pi itself. Before using Pi-Remote, install pi on the machine you want to control and make sure it runs: ```bash npm install -g @earendil-works/pi-coding-agent ``` Requirements: Node ≥ 22.18. The following runs the full loop on one machine, no server involved: Windows: ```powershell npm install npm run relay # 127.0.0.1:7001 (extension channel) and 7002 (web UI) deploy\start-pi.cmd # in a second terminal: start pi ```

已知限制

长对话未虚拟化，UI 仅加载最近 300 条消息；relay 需要自管理服务器（本地循环模式除外）；仅支持个人单用户使用，无多用户权限系统。

查看 README 依据

- Remote bash is disabled by default and must be enabled explicitly on the local machine; its working directory is restricted to session directories and registered projects. - Conversation content is not persisted by default. Persistence is opt-in, with a 30-day retention. ## Known limitations - Long transcripts are not virtualized. The UI mounts the most recent 300 messages and loads older ones page by page. - The relay needs a server you manage (the local loop mode excepted). - Pi-Remote is designed for personal, single-user use. There is no multi-user permission system. ## Documentation