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.
Relationship to pi: Pi-Remote is a companion tool built for 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.
UI design mockup: desktop on the left, mobile on the right.
Features
- Live mirroring — output, tool calls, and status changes in the terminal sync to the browser in real time, with incremental catch-up after a reconnect.
- Remote input — send messages to the session from the browser. While pi is busy, messages can queue or steer, and delivery is confirmed.
- Remote commands — switch model and thinking level, compact manually, create / fork / clone sessions, navigate the session tree, and inspect usage. Commands execute in the local pi process.
- Multiple devices — several machines can share one relay. The UI lists each device, its online state, and its sessions, and can start a new session on a chosen device.
- QR device linking — run
attach --linkon the machine that runs pi; the terminal and a local window show a QR code and a pairing code. Scan it with a phone, verify the device info and the 2-digit check code on the confirmation page, and approve with the admin token — the device token is then written to the local.envautomatically. The manual pairing-code flow remains available. - 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 in a Cursor-style interface, with light and dark themes (or follow the system).
- Usage visibility — token and cost usage updates with the session and is shown in the UI status area.
- Connection gating — a device is reachable only while its attach window is running. Closing the window disconnects it immediately.
How it works
| Component | Location | Role |
|---|---|---|
| Sync extension | extension/pi-remote-sync.ts |
Runs inside the pi process. Forwards session events, receives remote messages and commands and executes them locally, reconnects after drops |
| Relay | relay/ |
Node service running on a server. Handles authentication, forwarding, and the device/session index. Holds no model credentials and no local files |
| Web UI | ui/ |
Served by the relay. Renders the session stream, sends messages and commands, manages devices and sessions |
The full protocol definition is in readyUI/data-interface.md.
Quick start
Prerequisite: install pi on your device first. Pi-Remote is a companion tool for 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:
No comments yet.