# 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](#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

```bash
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:

```bash
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.

![pi remote control on iPhone](assets/screenshot-mobile.png)

---

## 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/`](./docs/):

| File | Purpose |
|---|---|
| [`docs/NEXT-STEPS.md`](./docs/NEXT-STEPS.md) | Current state + what to do next |
| [`docs/PHASE-1-sidecar.md`](./docs/PHASE-1-sidecar.md) | Sidecar production-ready |
| [`docs/PHASE-2-ios-mvp.md`](./docs/PHASE-2-ios-mvp.md) | iOS app MVP |
| [`docs/PHASE-3-ios-augmentation.md`](./docs/PHASE-3-ios-augmentation.md) | iOS polish features |
| [`docs/SYNC.md`](./docs/SYNC.md) | Multi-agent coordination |
| [`docs/reference/SPEC-ios-app.md`](./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.