568931901d
Create the modular server/ layout from PHASE-1-sidecar.md §Architecture Sketch: server/types.ts — shared WsClient/WsServer/RemoteServer interfaces server/upgrade.ts — WS upgrade routing per path (LEGACY /ws) server/server.ts — HTTP bootstrap, middleware, LEGACY HTML routes server/routes/ — empty dir, placeholder for T-1.5/T-1.6/T-1.7 The original extensions/remote-control/server.ts is replaced with a thin re-export shim so that index.ts continues to resolve './server.js' without changes. All LEGACY code paths (manifest.json, icon.svg, /, /ws) are tagged with // LEGACY: … comments. No behaviour changes. No new endpoints. Pre-existing biome errors in auth.ts, config.ts, index.ts are unchanged — NOT introduced by this commit. |
||
|---|---|---|
| .husky | ||
| assets | ||
| docs | ||
| extensions/remote-control | ||
| .gitignore | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| biome.json | ||
| package-lock.json | ||
| package.json | ||
README.md
pi-remote-control
A pi extension that exposes running sessions over WebSocket — used today
as a browser-based remote control, and the foundation for a native iOS app
currently in development.
Disclaimer
Personal use and research only. Provided as-is, no liability for damage, misuse, or operational consequences. See Security notes.
Current state: browser client
The extension ships a working HTML/WebSocket client that mirrors a pi session in any browser — including iPhone Safari.
Install
pi install git:git.vpsj.de/jay/pi-remote-control
Usage
Run /remote-control inside pi to open the menu:
- Turn on / Turn off — start or stop the server
- Configure URL — set the base URL for your tunnel or proxy
- Status — show the QR code and current session URL
To start the server automatically:
pi --remote-control
The server binds to 127.0.0.1 and is reached through a local tunnel
(e.g. Surge Ponte, Tailscale). Open the QR URL in any browser.
In development: native iOS app
A native iOS app is being built on top of this extension's WebSocket infrastructure. Design goals:
- Byte-exact mirror of the terminal session — what you see over SSH is what you see on the phone, rendered via SwiftTerm.
- Session persistence — sessions run for days, the app reconnects instantly after backgrounding (< 1s, via sequence-cursor delta replay).
- Multi-session — spawn, name, and switch between pi sessions from the phone as easily as browser tabs.
- Pi-aware augmentation — modifier bar tuned for pi (Ctrl, Esc, Tab, arrows, Shift+Enter), slash-command palette, status bar showing what pi is currently doing, push notifications when pi is waiting for input.
- QR pairing — scan once, self-signed TLS + token pinned automatically.
Architecture (in progress)
pi (Ink TUI) ◄──► tmux session ◄──► SSH (Mac terminal)
│
tmux -C (control mode)
│
pi-remote sidecar (this extension, extended)
│ wss:// (binary ANSI + JSON side-channel)
▼
iOS app (SwiftUI + SwiftTerm)
Streaming uses tmux control mode (tmux -C) rather than pipe-pane —
verified reliable across alternate-screen transitions in a PoC spike.
Implementation docs
All planning and coordination lives in docs/:
| File | Purpose |
|---|---|
docs/NEXT-STEPS.md |
Current state + what to do next |
docs/PHASE-1-sidecar.md |
Sidecar production-ready |
docs/PHASE-2-ios-mvp.md |
iOS app MVP |
docs/PHASE-3-ios-augmentation.md |
iOS polish features |
docs/SYNC.md |
Multi-agent coordination |
docs/reference/SPEC-ios-app.md |
Full feature spec (v3) |
Security notes
- The server only listens on localhost. Remote access depends on your tunnel.
- No multi-user authentication. The connection URL is a per-session secret.
- iOS app (in development) uses bearer tokens stored in the iOS Keychain, self-signed TLS with fingerprint pinning via QR pairing, and optional Face-ID gate — no CA or public PKI required.
- If using a reverse proxy, terminate TLS there and do not expose the dynamic backend port directly.