What it does

Pi-Remote is a companion tool for pi, a terminal coding agent. Instead of forking or replacing pi, it attaches through pi's official extension API: the session keeps running in the local pi process, and the browser receives a real-time mirror — output, tool calls and status changes — while also being able to send messages and commands back. It targets people who already use pi and want to monitor or drive a long-running session from another device, often a phone.

The system has three parts: a sync extension inside pi that forwards events and executes remote commands locally, a Node relay that handles authentication and routing without holding model credentials or local files, and a web UI served by the relay (component breakdown). The wire protocol and supported commands are documented in the data interface spec, and the terminal-vs-remote capability inventory lives in a separate inventory.

Beyond live output and queued/steering messages, remote commands cover switching model and thinking level, manual compaction, creating/forking/cloning sessions, navigating the session tree, and checking token and cost usage. Multiple machines can point at one relay, each listed with online state and sessions; a device is reachable only while its attach window stays open.

Quick start

Install pi first — Pi-Remote does not bundle it (prerequisites):

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

Node >= 22.18 is required. To run the whole loop on one machine without a server on macOS or Linux:

npm install
npm run relay          # extension channel on 127.0.0.1:7001, web UI on 7002
node deploy/setup.cjs ws://127.0.0.1:7001
deploy/sync-extension.sh   # installs the extension into ~/.pi/agent/extensions/
deploy/attach.sh           # opens the attach window; device comes online
deploy/start-pi.sh         # run in a second terminal

On Windows, run npm install, then npm run relay, then deploy\start-pi.cmd in a second terminal (platform commands). Open http://127.0.0.1:7002 and log in with the viewer token from .env. For a shared relay, systemd setup, token management and troubleshooting, use the deployment guide.

Constraints and security

The extension channel and web UI use separate tokens, both config files are gitignored, and the extension channel binds to 127.0.0.1 by default (security model). Anyone with the viewer token can send messages, and pi runs with tool permissions, so the token should be treated as a password; for internet access, use a private network, tunnel or TLS reverse proxy rather than exposing port 7002. Remote bash is off by default and, when enabled, is limited to session directories and registered projects. Conversation content is not persisted unless opted in, with a 30-day retention.

Known limits: transcripts are not virtualized — only the latest 300 messages are mounted and older ones load page by page; the relay generally needs a server you manage (local loop mode excepted); there is no multi-user permission system, so the design assumes personal, single-user use (limitations). The project is MIT-licensed.

HotRepo's take

Pi-Remote entered the TypeScript new-project snapshot on 2026-11-02 with 53 stars gained over the window from 2026-11-01 to 2026-11-02, landing at 212 total stars. The sampled curve starts near 102 stars on 2026-10-30 and climbs steadily, with two visible step-ups around 2026-10-31 15:00 UTC and 2026-11-01 14:00 UTC. There is no all-language daily rank recorded, and the only tracked discussion data has no matching threads, so the available evidence is limited to this short star series. What stands out technically is the architectural choice: a thin extension plus relay plus UI means pi itself is untouched and the remote surface can be swapped out, which makes the single-user security tradeoff (viewer token equals full send capability) the main thing to weigh before deploying.